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21. Objects, Message Passing, and Flavors 

The objccl-oricnied programming style used in die Smalltalk and Actor families of languages 
is available in ZeUilisp and used by tlie Tisp Machine software system. Its purpose is to perform 
generic operations on objects. I'art of its implementation is simply a convention in procedure¬ 
calling style; part is a powerful language feature, called Flavors, for defining abstract objects, 
lliis chapter attempts to explain what programming with objects and with message passing means, 
tlic various means of implementing tliese in ZeUilisp, and when you should use tliem. it assumes 
no prior knowledge of any other languages. 


21.1 Objects 

When writing a program, it is often convenient to model what tlie program does in terms of 
objects, conceptual entities that can be likened to real-world things. Choosing what objects to 
provide in a program is very important to tlie proper organization of the program. In an object- 
oriented design, specifying what objects exist is die first uisk in designing the system. In a text 
editor, die objects might be “pieces of text”, “pointers into text”, and “display windows”. In an 
electrical design system, the objects might be “resistors”, “capacitors”, “transistors”, “wires”, and 
“display windows”. After specifying what objects there arc, the next task of the design is to 
figure out what operations can be performed on each object. In die text editor example, 
operations on “pieces of text” might include inserting text and deleting text; operations on 
“pointers into text” might include moving forward and backward; and operations on “display 
windows” might include redisplaying the window and changing which “piece of text” the window 
is associated with. 

In this model, we think of die program as being built around a set of objects, each of which 
has a set of operations that can be performed on it. More rigorously, the program defines several 
types of object (the editor above has three types), and it can create many instances of each type 
(that is, there can be many pieces of text, many pointers into text, and many windows). The 
program defines a set of types of object and, for each type, a set of operations that can be 
performed on any object of the type. 

The new types may exist only in the programmer’s mind. For example, it is possible to think 
of a disembodied property list as an abstract data type on which certain operations such as get 
and putprop arc defined. ITiis type can be instantiated with (cons nil nil) (that is, by evaluating 
diis form you can create a new disembodied property list); the operations are invoked through 
ftmetions defined just for that purpose. 'Die fact that disembodied property lists are really 
implemented as lists, indistinguishable from any other lists, does not invalidate tliis point of view. 
However, such conceptual data types cannot be distinguished automatically by the system; one 
cannot ask “is this object a disembodied property list, as opposed to an ordinary list”. 

The defstruct for ship early in chapter 20 defines another conceptual type, defstruct 
automatically defines some operations on this object, the operations to access its elements. We 
could define other functions that did useful things with ship’s, such as computing their speed, 
angle of travel, momentum, or velocity, stopping them, moving them elsewhere, and so on. 
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In both eases, we represent our conceptual object by one l.isp object, the l.isp object we use 
for the representation has structure and refers to other l.isp objects. In the disembodied property 
list ease, Uk l.isp object is a list of pairs; in die ship ease, the l.isp object is an array whose 
dcUtils are Utken care of by defstruct. In both cases, we can say Uiat the object keeps Hack of 
an internal state, which can be examined and altered by the operations available for tltat type of 
object, get examines die state of a property list, and putprop alters it; ship-x-position 
examines die state of a ship, and {setf (ship-x-position ship) 5.0) alters it. 

We have now seen the essence of object-oriented programming. A conceptual object Is 
modeled by a single l.isp object, which bundles up some suite information. Kor every type of 
object, diere is a set of operations diat can be performed to examine or alter die suite of the 
object. 

21.2 Modularity 

An important benefit of the object-oriented style is that it lends itself to a pardcularly simple 
and lucid kind of modularity. If you have modular programming constructs and techniques 
available, they help and encourage you to write programs that are easy to read and understand, 
and so are more reliable and maintainable. Object-oriented programming lets a programmer 
implement a useful facility that presents the caller with a set of external interfaces, without 
requiring the caller to understand how the internal details of the implementation work. In other 
words, a program that calls this facility can treat the facility as a black box; the program knows 
what die facility’s external interfaces guarantee to do, and that is all it knows. 

For example, a program that uses disembodied property lists never needs to know that the 
property list is being maintained as a list of alternating indicators and values; the program simply 
performs the operations, passing them inputs and getting back outputs. ITie program only 
depends on the external definition of these operations: it knows that if it putprop s a property, 
and doesn’t remprop it (or putprop over it), then it can do get and be sure of getting back the 
same thing it put in. The important thing about this hiding of die details of the implementation 
is that someone reading a program that uses disembodied property lists need not concern himself 
with how they are implemented; he need only understand what they undertake to do. This saves 
the programmer a lot of dme and lets him concentrate his energies on understanding the program 
he is working on. Another good thing about this hiding is that the representation of property fists 
could be changed and the program would continue to work. For example, instead of a fist of 
alternating elements, the property list could be implemented as an association fist or a hash table. 
Nothing in the calling program would change at all. 

The same is true of the ship example. The caller is presented with a collection of operations, 
such as ship-x-position, ship-y-position, ship-speed, and ship-direction; it simply calls these 
and looks at their answers, without caring how they did what they did. In our example above, 
ship-x-position and ship-y-position would be accessor functions, defined automatically by 
defstruct, while ship-speed and ship-direction would be functions defined by the implementor 
of the ship type. The code might look like this: 
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(defstruct (ship :conc-name) 
x-position 
y-position 
x-velocity 
y-velocity 
mass) 

(defun ship-speed (ship) 

(sqrt (+ (ship-x-velocity ship) 2) 

{'' (ship-y-velocity ship) 2)))) 

(defun ship-direction (ship) 

(atan2 (ship-y-velocity ship) 

(ship-x-velocity ship))) 

The caller need not know that tlie first two functions were structure accessors and that the 
second two were written by hand and do aritlimctic. 'Fhosc facts would not be considered part of 
the black box characteristics of the implementation of the ship type. I'hc ship type docs not 
guarantee which functions will be implemented in which ways: such aspects arc not part of the 
contract between ship and its callers. In fact, ship could have been written this way instead: 

(defstruct (ship :conc-name) 
x-position 
y-position 
speed 
direction 
mass) 

(defun ship-x-velocity (ship) 

(♦ (ship-speed ship) (cos (ship-direction ship)))) 

(defun ship-y-velocity (ship) 

(* (ship-speed ship) (sin (ship-direction ship)))) 

In this second implementation of the ship type, we have decided to store the velocity in polar 
coordinates instead of rectangular coordinates. This is purely an implementation decision. The 
caller has no idea which of the two ways the implementation uses; he just performs the 
operations on the object by calling the appropriate functions. 

We have now created our own types of objects, whose implementations are hidden from the 
programs that use them. Such types are usually referred to as abstract types. The object-oriented 
style of programming can be used to create abstract types by hiding the implementation of the 
operations and simply documenting what the operations are defined to do. 

Some more terminology: the quantities being held by the elements of the ship structure are 
referred to as instance variables. Each instance of a type has the same operations defined on it; 
what distinguishes one instance from another (besides eq-ness) is the values that reside in its 
instance variables. The example above illustrates that a caller of operations docs not know what 
the instance variables are; our two ways of writing the ship operations have different instance 
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variables, but from the outside they have exactly the same operations. 

One might ask: “But what if the caller evaluates (aref ship 2) and notices that he gets back 
die .y velocity ratlicr than die speed? fhen he can tell which of the two implementations were 
used." This is true; if the caller were to do diat. he could tell. However, when a facility is 
implemented in die object-oriented style, only certain functions arc documented and advertised, 
die functions that arc considered to be operations on the type of object, fhe contract from ship 
to its callers only speaks about what happens if die caller calls these functions. Ihc contract 
makes no guarantees at all about what would happen if the caller were to start poking around on 
his own using aref. A caller who docs so is in error, he is depending on something that is not 
specified in the contract. No guarantees were ever made about die results of such action, and so 
anything may happen; indeed, ship may get reimplcmcntcd overnight, and die code that docs the 
aref will have a dilfcrcnt effect entirely and probably stop working. 'I'his example shows why the 
concept of a contract between a callec and a caller is important; die contract specifies the 
interface between the two modules. 

Unlike some other languages diat provide abstract types, Zetalisp makes no attempt to have 
the language automatically forbid constructs diat circumvent the contract. Ihis is intentional. One 
reason for this is that die Lisp Machine is an interactive system, and so it is important to be able 
to examine and alter internal state interactively (usually from a debugger). Furthennorc, there is 
no strong distinedon between die “system” programs and the “user” programs on the Lisp 
Machine: users are allowed to get' into any part of the language system and change what they 
want to change. Another reason is the traditional MIT AI Lab philosophy that opposes “fascist” 
restrictions which impose on the user “for his own good”. The user himself should decide what is 
good for him. 

In summary: by defining a set of operations and making only a specific set of external 
entrypoints available to the caller, the programmer can create his own abstract types. These types 
can be useful facilities for other programs and programmers. Since the implementadon of the 
type is hidden from the callers, modularity is maintained and the implementadon can be changed 
easily. 

We have hidden the implementation of an abstract type by making its operations into 
functions which the user may call. The important thing is not that they are functions in Lisp 
everything is done with functions. I'he important thing is that we have defined a new conceptual 
operation and given it a name, rather than requiring anyone who wants to do the operation to 
write it out step-by-step, "fhus we say (ship-x-velocity s) rather than (aref s 2). 

Often a few abstract operation functions are simple enough that it is desirable to compile 
special code for them rather than really calling the function. (Compiling special code like this is 
often called open-coding.) The compiler is directed to do this through use of macros, substs, or 
optimizers, defstruct arranges for this kind of special compilation for the funedons that get the 
instance variables of a structure. 

When we use this optimizadon, the implementadon of the abstract type is only hidden in a 
certain sense. It does not appear in the Lisp code written by the user, but does appear in the 
compiled code. Ihe reason is that there may be some compiled functions that use the macros (or 
whatever); even if you change the definition of the macro, the existing compiled code will 
continue to use the old definition, 'fhus, if the implementation of a module is changed programs 


PS:<L.MAN>n.AVOR.TEXT.134 


8-JUN-84 




(icncric Opcraiioiis 


I isp Miichinc Manual 405 

tliat use it may need to be recompiled. I’his is something we sometimes accept for the sake of 
efficiency. 

In the present implementation of flavors, which is discussed below, there is no such compiler 
incorporation of nonmodiilar knowledge into a program, except when tlie :ordered-instance- 
variables feature is used: see page 427, where this problem is explained further. If you don’t 
use the ;ordered-instance-variables feature, you don’t have to worry about this. 


21.3 Generic Operations 

Suppose we ffiink about the rest of the program that uses the ship abstraction. It may want 
to deal with other objects ffiat arc like ship’s in that they arc movable objects with mass, but 
unlike ships in other ways. A more advanced model of a ship might include the concept of the 
ship's engine power, the number of passengers on board, and its name. An object- representing a 
meteor probably would not have any of these, but might have another attribute such as how 
much iron is in it. 

However, all kinds of movable objects have positions, velocities, and masses, and the system 
will contain some programs that deal with dicse quantities in a uniform way, regardless of what 
kind of object the attributes apply to. For example, a piece of the system that calculates every 
object’s orbit in space need not worry about the other, more peripheral attributes of various types 
of objects; it works the same way for all objects. Unfortunately, a program that tries to calculate 
die orbit of a ship needs to know die ship’s attributes, and must therefore call ship-x-position 
and ship-y-velocity and so on. The problem is that these ffinctions won’t work for meteors. 
ITicre would have to be a second program to calculate orbits for meteors that would be exaedy 
the same, except that where the first one calls ship-x-position, the second one would call 
meteor-X-position, and so on. This would be very bad; a great deal of code would have to 
exist in multiple copies, all of it would have to be maintained in parallel, and it would take up 
space for no good reason. 

What is needed is an operation that can be performed on objects of several different types. 
For each type, it should do the thing appropriate for that type. Such operations are called 
generic operations, 'Hie classic example of generic operations is the arithmetic functions in most 
programming languages, including Zctalisp. The + (or plus) function accepts integers, floats, 
ratios and complex numbers, and perform an appropriate kind of addition, based on the data 
types of the objects being manipulated. In our example, we need a generic x-position operation 
that can be performed on either ship’s, meteor’s, or any other kind of mobile object represented 
in the system. This way, we can write a single program to calculate orbits. When it wants to 
know the x position of the object it is dealing with, it simply invokes the generic x-positior» 
operation on the object, and whatever type of object it has, the correct operation is performed, 
and the x position is returned. 

Another terminology for the use of such generic operations has emerged from the Smalltalk 
language: performing a generic operation is called sending a message. I’hc message consists of an 
operation name (a symbol) and arguments. ITie objects in the program are thought of as little 
people, who get sent messages and respond with answers (returned values). In the example above, 
the objects arc sent x-position messages, to which they respond with their x position. 
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Sending a message is a way of invoking a function without specifying which function is to be 
called. Instead, the data determines the function to use. 'Ilic caller specifics an operation name 
and an object; that is, it said what operation to perform, and what object to perform it on. 1110 
function to invoke is found from tliis information. 

'I’hc two data used to figure out which function to call arc tlic type of the object, and the 
name of the operation. The same set of functions arc used for all instances of a given type, so 
the type is the only attribute of the object used to figure out which function to call. The rest of 

the message besides tlic operation is data which arc passed as arguments to tlic function, so the 

operation is die only part of die message used to find the function. Such a function is called a 
method. For example, if we send an x-position message to an object of type ship, then the 
function we find is "the ship type's x-position mcdiod”. A mcdiod is a function that handles a 
specific operation on a specific kind of object; this mcdiod handles messages named x-position to 
objects of type ship. 

In our new tcmiinology: the orbit-calculating program finds the x position of the object it is 
working on by sending .diat object a message consisting of the operation x-position and no 
arguments. The returned value of the message is the x position of the object. If the object was 
of type ship, then die ship type's x-position method was invoked; if it was of type meteor, 
then the meteor type’s x-position mediod was invoked. The orbit-calculating program just sends 
the message, and the right function is invoked based on the type of die object. We now have 

true generic functions, in the fonn of message passing; the same operation can mean different 

things depending on the type of the object. 

21.4 Generic Operations in Lisp 

How do we implement message passing in Lisp? Our convention is that objects that receive 
messages are always Junctional objects (that is, you can apply them to arguments). A message is 
sent to an object by calling that object as a function, passing the operation name as the first 
argument and the arguments of the message as the rest of the arguments. Operation names are 
represented by symbols; normally these symbols are in the keyword package (see chapter 27, page 
636), since messages are a protocol for communication between different programs, which may 
reside in different packages. So if we have a variable my-ship whose value is an object of type 
ship, and we want to know its jc position, we send it a message as follows: 

(send my-ship :x-position) 

To set the ship’s x position to 3.0, we send it a message like this: 

(send my-ship :set :x-position 3.0) 

It should be stressed that no hew features are added to Lisp for message sending; we simply 
define a convention on the way objects take arguments. The convention says that an object 
accepts messages by always interpreting its first argument as an operation name. The object must 
consider this operation name, find the function which is the method for that operation, and 
invoke that function. 
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Generic Operalions in I .isp 


send object operation &rcst arguments 

Sends object a message with operation and arguments as specified. Currently send is 
identical to funcall, but preferable when a message is being sent, just for clarity. 

'fhcrc arc vague ideas of making send different from funcall if object is a symbol, list, 
number, or other object that docs not normally handle messages when funcallcd, but the 
meaning of Uiis is not completely clear. 

lexpr-send object operation &rcst arguments 
Currently lexpr-send is the SJtmc as apply. 

'Hiis raises the question of how message receiving works. The object must somehow find the 
right method for the message it is sent. Furthermore, the object now has to be callable as a 
function. But an ordinary function will not do. We need something that can store the instance 
variables (the internal stale) of the object. We need a function with internal state; that is, we 
need a coroutine. 

Of the Zctalisp features presented so far, tlic most appropriate is the closure (see chapter 12, 
page 250). A message-receiving object could be implemented as a closure over a set of instance 
variables. 'Fhc function inside the closure would have a big selectq form to dispatch on its first 
argument. (Actually, rather tJian using closures and a selectq, you would probably use entities 
(section 12.4, page 255) and defselect (page 236).) 

While using closures (or entities) docs work, it has several serious problems. The main 
problem is that in order to add a new operation to a system, it is necessary to modify a lot of 
code; you have to find all the types that understand that operation, and add a new clause to the 
selectq. ITie problem witli this is that you cannot textually separate the implementation of your 
new operation from the rest of the system; the methods must be interleaved with the other 
operations for the type. Adding a new operation should only require adding Lisp code; it should 
not require modifying Lisp code. 

'fhe conventional way of making generic operations is to have a procedure for each operation, 
which has a big selectq for all the types; this means you have to modify code to add a type. 
The way described above is to have a procedure for each type, which has a big selectq for all 
the operations; this means you have to modify code to add an operation. Neither of tliese has 
the desired property that extending the system should only require adding code, rather than 
modifying code. 

Closures (and entities) are also somewhat clumsy and crude. A far more streamlined, 
convenient, and powerful system for creating message-receiving objects exists; it is called the 
flavor mechanism. With flavors, you can add a new method simply by adding code, without 
modifying anything. Furthermore, many common and useful things are very easy to do with 
flavors. The rest of this chapter describes flavors. 
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21.5 Simple Use of Flavors 

A in its simplest fonn, is a definition of an abstract type. New flavors arc created 

with the defflavor special form, and mctliods of the flavor arc created with tlic defmethod special 
foim. New instances of a flavor arc created with the make-instance function. 'Iliis section 
explains simple uses of these forms. 

K()r an example of a simple use of flavors, here is how die ship example above would be 
implemented, 

(defflavor ship (x-position y-position 

x-velocity y-velocity mass) 

0 

:gettable-instance-variables) 

(defmethod (ship tspeed) () 

(sqrt (+ (" x-velocity 2) 

(- y-velocity 2)))) 

(defmethod (ship rdirection) () 

(atan2 y-velocity x-velocity)) 

The code above creates a new flavor. The first subform of die defflavor is ship, which is the 
name of the new flavor. Next is die list of instance variables; they are the five that should be 
familiar by now. llic next subfoim is something we will get to later. The rest of the subforms 

arc the body of the defflavor, and each one specifics an option about this flavor. In our 

example, there is only one option, namely :gettable-instance-variables, lliis means that for 
each instance variable, a method should automatically be generated to return the value of that 
instance variable. ITie name of the operation is a symbol with the same name as the instance 
variable, but interned on the keyword package. Thus, methods are created to handle the 
operations :x-position, :y-position, and so on. 

Each of the two defmethod forms adds a method to the flavor. The first one adds a handler 
to the flavor ship for die operation :speed. The second subform is the lambda-list,. and the rest 
is the body of the function that handles the :speed operation. The body can refer to or set any 
instance variables of the flavor, just like variables bound by a containing let. When any instance 
of the ship flavor is invoked with a first argument of :direction, the body of the second 
defmethod is evaluated in an environment in which the instance variables of ship refer to the 

instance variables of this instance (the one to which the message was sent). So the arguments 

passed to cli:atan are the the velocity components of this particular ship. The result of clhatan 
becomes the value returned by the :direction operation. 

Now we have seen how to create a new abstract type; a new flavor. Every instance of this 
flavor has the five instance variables named in the defflavor form, and the seven methods we 
have seen (five that were automatically generated because of the :gettable-instance-variables 
option, and two that we wrote ourselves). The way to create an instance of our new flavor is 
with the make-instance function. Here is how it could be used: 
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(setq ray-ship (raake-instance ’ship)) 

This returns an object whose printed representation is #<SHIP 13731210>. (Of course, tlie 
value of the magic number will vary; it is just the object address in (Ktal.) The argument to 
make-instance is die name of the flavor to be instantiated. Additional arguments, not used here, 
are /«// opiions, that is, commands to tlic flavor of which we are making an instance, selecting 
optional features. 'I his will be discussed more in a moment. 

Hxamination of the flavor we have defined shows that it is quite useless as it stands, since 
there is no way to set any of the parameters. We can fix this up easily by putting tlie :settable- 
instance-variables option into tlie defflavor form. This option tells defflavor to generate 
methods for operation :set for first argument :x-position. :y-position, and so on; each such 
mcUiod takes one additional argument and sets the corresponding insuincc variable to that value. 
It also generates methods for the operations :set-x-position, :set-y-position and so on; each of 
tlicse takes one argument and sets the corresponding variable. 

Another option wc can add to the defflavor is :inittable-instance-variables, which allows us 
to initialize die values of the instance variables when an instance is first created, rinittable- 
instance-variables docs not create any methods; instead, it makes initializalion keywords named 
:x-position, :y-position, etc., that can be used as init-option arguments to make-instance to 
initialize the corresponding instance variables, 'fhe list of init options is sometimes called the init- 
plist because it is like a property list. 

Here is the improved defflavor: 

(defflavor ship (x-position y-position 

x-velocity y-velocity mass) 

0 

:gettable-instance-variables 
:settable-instance-variables 
:inittable-instance-variables) 

All we have to do is evaluate this new defflavor, and the existing flavor definition is updated 
and now includes the new methods and inidalization options. In fact, the instance wc generated a 
while ago now accepts the new operaUons! We can set the mass of the ship wc created by 
evaluating 

(send ray-ship :set-mass 3.0) 
or 

(send ray-ship :set :mass 3.0) 

and the mass instance variable of my-ship is properly set to 3.0. Whether you use :set-mass 
or the general operation :set is a matter of style; :set is used by the expansion of (setf (send 
my-ship imass) 3.0). 

If you want to play around with flavors, it is useful to know that describe of an instance 
tells you the flavor of the instance and the values of its instance variables. If wc were to evaluate 
(describe my-ship) at this point, the following would be printed: 
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iS^SHIP 13731210>. an object of flavor SHIP, 
has instance variable va-IOes: * 


X-POSITION 
Y-POSITION 
X-VELOCITY 
Y-VELOCITY 
MASS: 


void 

void 

void 

void 

3.0 


Now that tlic insbincc variables im inittablc, wc can create another ship and initiali/c some of 
the insuince variables using the init-plist. Let's do that and describe the result: 

(setq her-ship {make-instance ’ship :x-position 0.0 

:y-position 2.0 
:mass 3.5)) 

=> #<SHIP 13756521> 


(describe her-ship) 

#<SHIP 13756521>. an object of flavor SHIP, 
has instance variable values; 


X-POSITION: 

0.0 

Y-POSITION: 

2.0 

X-VELOCITY: 

void 

Y-VELOCITY: 

void 

MASS: 

3.6 


A flavor can also establish default initial values for instance variables. These default values are 

used when a new instance is created if the values are not initialized any other way. The syntax 

for specifying a default initial value is to replace the name of the instance variable by a list, 

whose first element is the name and whose second is a form to evaluate to produce the default 

initial value. For example: 
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(defvar *default-x-velocity* 2.0) 

(defvar ♦defauH-y-ve1ocity* 3.0) 

(defflavor ship ((x-position 0.0) 

(y-position 0.0) 

(x-velocity ♦default-x-ve1ocity*) 
(y-velocity ♦default-y-velocity•) 
mass) 

{) 

:gettab1e-instance-variables 
:settable-instance-variables 
:inittable-instance-variables) 

(setq another-ship (make-instance ’ship :x-position 3.4)) 
=> #<SHIP 14563643> 

(describe another-ship) 

#<SHIP 14563643>, an object of flavor SHIP, 
has instance variable values: 


X-POSITION: 

3.4 

Y-POSITION: 

0,0 

X-VELOCITY: 

2.0 

Y-VELOCITY: 

3.0 

MASS: 

void 


x-position was initialized explicitly, so the default was ignored, y-position was initialized 
from the default value, which was 0.0. The two velocity instance variables were initialized from 
their default values, which came from two global variables, mass was not explicitly initialized 
and did not have a default initialization, so it was left void. 

There arc many other options that can be used in defflavor, and the init options can be used 
more flexibly tlian just to initialize instance variables; full details are given later in tills chapter. 
But even with the small set of features we have seen so far, it is easy to write object-oriented 
programs. 

21.6 Mixing Flavors 

Now we have a system for defining message-receiving objects so that we can have generic 
operations. If we want to create a new type called meteor tliat would accept the same generic 
operations as ship, we could simply write another defflavor and two more defmethod’s that 
looked just like those of ship, and then meteors and ships would both accept the same 
operations, ship would have some more instance variables for holding attributes specific to ships 
and some more methods for operations that are not generic, but arc only defined for ships; the 
same would be true of meteor. 

However, this would be a a wasteful thing to do. ITie same code has to be repeated in 
several places, and several instance variables have to be repeated. 'Hie code now needs to be 
maintained in many places, which is always undesirable. 'Hie power of flavors (and the name 
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“flavors”) comes from the ability to mix several flavors and get a new flavor. Since the 
functionality of ship and meteor partially overlap, we can take die common functionality and 
move it into its own flavor, which might be called moving-object. We would define moving- 
object die same way as we defined ship in die previous section. Lhen, ship and meteor could 
be defined like this: 

(defflavor ship (engine-power number-of-passengers name) 
(moving-object) 

:gettable-instance-variables) 

(defflavor meteor (percent-iron) 

(moving-object) 

:inittable-instance-variables) 

rhese defflavor forms use die second subfonn, which we ignored previously. 'Hie second 
subform is a list of flavors to be combined to form the new flavor; such flavors are called 
components. Concentrating on ship for a moment (analogous diings are true of meteor), we see 
that it has exactly one component flavor: moving-object. It also has a list of instance variables, 
which includes only the ship-specific instance variables and not the ones that it shares with 
meteor. By incorporating moving-object, die ship flavor acquires all of its instance variables, 
and so need not name them again. It also acquires all of moving-object’s methods, too. So 
with the new definition, ship instances still implement die :x-velocity and :speed operations, 
with the same meaning as before. However, did :engine-power operation is also understood 
(and returns die value of the engine-power instance variable). 

What we have done here is to take an abstract type, moving-object, and build two more 
specialized and powerful abstract types on top of it. Any ship or meteor can do anything a 
moving object can do, and each also has its own specific abilities. This kind of building can 
continue; we could define a flavor called ship-with-passenger that was built on top of ship, 
and it would inherit all of moving-object’s instance variables and mcdiods as well as ship’s 
instance variables and mediods. Furthermore, the second subform of defflavor can be a list of 
several components, meaning that the new flavor should combine all the instance variables and 
methods of all the flavors in die list, as well as the ones those flavors are built on, and so on. 
All the components taken together form a big tree of flavors. A flavor is built from its 
components, its components’ components, and so on. We sometimes use die term “components” 
to mean die immediate components (the ones listed in the defflavor), and sometimes to mean all 
the components (including the components of die immediate components and so on). (Actually, it 
is not strictly a tree, since some flavors might be components through more than one path. It is 
really a directed graph; it can even be cyclic.) 

The order in which the components are combined to form a flavor is important. 'Fhe tree of 
flavors is turned into an ordered list by performing a top-down, depth-first walk of the tree, 
including non-terminal nodes before die subtrees diey head, ignoring any flavor that has been 
encountered previously somewhere else in the tree. For example, if flavor-1’s immediate 
components are flavor-2 and flavor-3, and flavor-2’s components arc flavor-4 and flavor-5, 
and flavor-3’s component was flavor-4, then die complete list of components of flavor-1 would 
be: 

flavor-l, flavor-2, flavor-4, flavor-5, flavor-3 
Ihe flavors earlier in this list are die more specific, less basic ones; in our example, ship-with- 
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passengers would be first in die list, followed by ship, followed by moving-object. A flavor is 
always die first in the list of its own components. Notice diat flavor-4 does not appear twice in 
diis list. Only the first (xrcurrcncc of a flavor appears; duplicates arc removed. ( Ilic elimination 
of duplicates is done during die walk; if dicrc is a cycle in die directed graph, it docs not cause 
a non-terminating computation.) 

fhe set of insuince variables for the new flavor is the union of all die sets of instance 
variables in all die component flavors. If both flavor-2 and flavor-3 have instance variables 
named foo, then flavor-1 has an instance variable named foo, and any mcdiods that refer to foo 
refer to diis same insUincc variable. Thus different components of a flavor can communicate with 
one another using shared insUincc variables, (rypically, only one component ever sets the 
variable; the others only look at it.) Hie default initial value for an insUuicc variable comes from 
die first component flavor to specify one. 

'fhe way the mcdiods of die components arc combined is the heart of the flavor system. 
When a flavor is defined, a single function, called a combined method, is constructed for each 
operation supported by the flavor. 'Hiis function is constmeted out of all the mcdiods for that 
operation from all the components of the flavor. There are many different ways that mediods can 
be combined; these can be selected by die user when a flavor is defined. The user can also 
create new forms of combination. 

There arc several kinds of methods, but so far, the only kinds of methods we have seen are 
primary methods. 'ITic default way primary methods are combined is that all but the earliest one 
provided arc ignored. In other words, the combined mcdiod is simply die primary method of the 
first flavor to provide a primary mcdiod. What this means is that if you arc starting with a flavor 
foo and building a flavor bar on top of it, then you can override foo’s method for an operation 
by providing your own mcdiod. Your method will be called, and foo’s will never be called. 

Simple overriding is often useful; for example, if you want to make a new flavor bar that is 
just like foo except that it reacts completely differently to a few operations. However, often you 
don’t want to completely override the base flavor’s (foo’s) method; sometimes you want to add 
some extra things to be done. This is where combination of methods is used. 

The usual way methods are combined is that one flavor provides a primary method, and other 
flavors provide daemon methods. The idea is that the primary method is “in charge” of the main 
business of handling the operation, but other flavors just want to keep informed that die message 
was sent, or just want to do the part of the operation associated with their own area of 
responsibility. 

daemon methods come in two kinds, before and after. 'There is a special syntax in defmethod 
for defining such methods. Here is an example of the syntax. 'To give the ship flavor an after¬ 
daemon method for the :speed operation, the following syntax would be used: 

(defmethod (ship rafter :speed) () body) 

Now, when a message is sent, it is handled by a new function called the combined method. 
The combined method first calls all of the before daemons, then the primary method, then all the 
after daemons. Each method is passed the same arguments that the combined method was given. 
I'he returned values from the combined method are the values returned by the primary method; 
any values returned from the daemons are ignored. Before-daemons are called in the order that 
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flavors arc combined, while after-daemons arc called in the reverse order. In other words, if you 
build bar on lop of foo, tben bar's before-daemons run before any of tliosc in too, and bar’s 
after-daemons run after any of those in foo. 

The reason for this order is to keep the modularity order correct. If we create flavor-1 built 
on flavor-2, tben it should not matter what flavor-2 is built out of. Our new before-daemons 
go before all methods of flavor-2, and our new after-daemons go after all methods of flavor-2, 
Note tliat if you have no daemons, this reduces to the form of combination described itbovc. The 
most.recently added component flavor is llie highest level of abstraction; you build a higher-level 
object on top of a lower-level object by adding new components to the front. The syntax for 
defining daemon metliods can be found in the description of defmethod below. 

I'o make tliis a bit more clear, let's consider a simple example tliat is easy to play with; tlic 
:print-self method, 'fhe l isp printer (i.e. die print function; see section 23.1, page 506) prints 
instiuices of flavors by sending them :print-self messages, fhe first argument to the :print-self 
operation is a stream (we can ignore die others for now), and die receiver of the message is 
supposed to print its printed representation on die stream. In die ship example above, die reason 
diat instances of the ship flavor printed die way diey did is because die ship flavor was actually 
built on top of a very basic flavor called vanilla-flavor; diis component is provided automatically 
by defflavor. It was vanilla-flavor's :print-self method that was doing die printing. Now, if we 
give ship its own primary method for the :print-seif operation, dicn that method completely 
takes over the job of printing; vanilla-flavor's mediod will not be called at all. However, if we 
give ship a before-daemon method for die :print-self operation, dien it will get invoked before 
the vanilla-flavor mediod, and so whatever it prints will appear before what van ilia-flavor prints. 
So we can use before-daemons to add prefixes to a printed representation; similarly, after- 
daemons can add suffixes. 

'fhere arc other ways to combine methods besides daemons, but diis way is the most 
common, 'fhe more advanced ways of combining methods arc explained in a later section; see 
section 21.11, page 433. vanilla-flavor and what it docs for you arc also explained later; see 
section 21.10, page 432. 

21.7 Flavor Functions 

def flavor Macro 

A flavor is defined by a form 

(defflavor flavor-name {varl var2...) {flavl flav2...) 
opil opt2 ...) 

flavoT^name is a symbol which serves to name this flavor. It is given an si:fiavor property 
which is die internal data-structure containing the details of the flavor. 

(type-of obj), where obj is an insuince of the flavor named flavor-name, returns the 
symbol flavor-name, (typep obj flavor-name) is t if obj is an instance of a flavor, one of 
whose components (possibly itsclO is flavor-name. 

varl, var2, etc. arc the names of the instance-variables containing the local state for this 
flavor. A list of the name of an instance-variable and a default inidalization form is also 
acceptable; die inidalization form is evaluated when an instance of the flavor is created if 
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no other initial value for tlic variable is obtained. If no initialization is .specified, the 
variable remains void. 

flavl. flav2, etc. arc the names of the component flavors out of which this flavor is built, 
’['he features of those flavors arc inherited as described previously. 

opfL opi2, etc. arc options; each option may be cither a keyword symbol or a list of a 
keyword symbol and arguments, 'nic options to defflavor arc described in section 21.8, 
page 424. 

•all-flavor-names* Variable 

A list of the names of all tlie flavors that have ever been defflavor’cd. 

defmethod ^tacro 

A method, that is, a function to handle a particular operation for insuinccs of a particular 
flavor, is defined by a form such as 

(defmethod [Jlavor'mme method-type operation) lambda-list 
form! form2 ...) 

flavor-name is a symbol which is the name of die flavor which is to receive the method. 
operation is a keyword symbol which names the operation to be handled, method-type is a 
keyword symbol for the type of method; it is omitted when you are defining a primary 
method. For some method-types, additional information is expected. It comes after 
operation. • 

ITie meaning of method-type depends on what style of method combination is declared for 
this operation. For instance, if :daemon combination (die default style) is in use, method 
types :before and :after are allowed. See section 21.11, page 433 for a complete 
description of method types and the way methods arc combined. 

lambda-list describes the arguments and aux variables of the function; the first argument 
to the mcdiod, which is the operation name itself, is automatically handled and so is not 
included in the lambda-list. Note that methods may not have unevaluated (Squote) 
arguments; that is. they must be functions, not special forms, formi, form2, etc, are the 
function body; the value of the last form is returned. 

The variant form 

(defmethod {flavor-name operation) Junction) 
where function is a symbol, says that flavor^name's method for operation is junction, a 
symbol which names a function. That function must take appropriate arguments; the first 
argument is the operation. When the function is called, self will be bound. 

If you redefine a method that is already defined, the old definition is replaced by the new 
one. Given a flavor, an operation name, and a method type, there can only be one 
function (with the exception of :case methods; see page 437), so if you define a ibefore 
daemon method for the foo flavor to handle tlie :bar operation, then you replace the 
previous before-daemon; however, you do not affect the primary method or methods of 
any other type, operation or flavor. 
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The function spec for a method (sec section 11.2, page 225) looks like: 

{;method Jlavni^nameopcralionf -or - 

(: me I hod flavor-mime method-type operation) or 

(:method flavor-name method-type operation suboperation) 

This is useful to know if you want to trace (page 738), breakon (page 741) or advise 
(page 742) a method, or if you want to poke around at the mctliod function itself, c.g. 
disassemble it (sec page 792). 

make-instance flavot^name init-option! valuel init-option2 value2... 

Creates and returns an insuincc of die specified flavor. Arguments after the first arc 
alternating init-option keywords and arguments to those keywords, i'hcsc options arc used 
to initialize insumcc variables and to select arbitrary options, as described above. An :init 
messtige is sent to tlic newly-created object with one argument, die init-plist. 'ITiis is a 
disembodied property-list containing die init-options specified and those defaulted from the 
flavor's idefault-init-plist (however, init keywords that simply initialize insutnee variables, 
and the corresponding values, may be absent when die :init methods arc called), make- 
instance is an casy-to-call interface to instantiate-flavor, below. 

If ;allo\w^other-keys is used as an init keyword with a non-nil value, this error check is 
suppressed. Then unrecognized keywords are simply ignored. Example: 

(make-instance ’foo :lose 5 :a1low-other-keys t) 
specifics the init keyword :lose, but prevents an error should the keyword not be handled. 

1 nstant 1 at 0 -flavor flavor-name init-pUst &optional send-init-message-p 
return-unhandled-keywords area 

This is an extended version of make-instance, giving you more features. Note that it 
takes the init-plist as an individual argument, rather than taking a rest argument of init 
options and values. 

The init-plist argument must be a disembodied property list; locf of a rest argument is 
satisfactory. Beware! This property list can be modified; the properties from the default 
init plist are putprop'cd on if not already present, and some :init methods do explicit 
putprop’s onto the init-plist. 

In the event that :init methods remprop properties already on the init-plist (as opposed to 
simply doing get and putprop), tJicn tlic init-plist is rplacd’cd. This means that the 
actual supplied list of options is modified. It also means tliat locf of a rest argument does 
not work; the caller of instantiate-flavor must copy its rest argument (e.g. with copylist); 
tliis is because rpiacd is not allowed on stack lists. 

Do not use nil as tlie init-plist argument. ITiis would mean to use the properties of the 
symbol nil as tlic init options. If your goal is to have no init options, you must provide 
a property list containing no properties, such as the list (nil). 

Here is the sequence of actions by which instantiate-flavor creates a new instance: 

First, the specified flavor's instantiation flavor function (page 429), if it exists, is called to 
determine which flavor should actually be instantiated. If tlicre is no instantiation flavor 
function, the specified flavor is instantiated. 
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If the flavor's nicihod hash'tablc and otlicr internal inforniatioh have not been computed 
or arc not up to date, lliey arc computed. This may take a substantial amount of time or 
even invoke Uic compiler, but it happens only once for each time you define or redefine 
a particular flavor. 

Next, the insuince itself is created. If the area argument is specified, it is the number of 
an area in which to cons tlic insuincc; otherwise die flavor’s instance area function is 
called to choose an area if there is one; otherwise, default-cons-area is used. See page 
429. 

riicn die initial values of die instance variables arc computed. If an insuince variable is 
declared inittablc, and a keyword with the same spelling as its name appears in inil-plisl, 
die property for that keyword is used as die initial value. 

Otherwise, if die default init plist specifics such a property, it is evaluated and the value 
is used. Otherwise, if die flavor definition specifics a default initialization form, it is 
evaluated and the value is used. The initialization form may not refer to any instance 
variables. It can find die new instance in self but should not invoke any operations on it 
and should not refer directly to any insUincc variables. It can get at instance variables 
using accessor macros created by the loutside-accessible-instance'variables option 
(page 427) or the function symeval-in-instance (page 423). 

If an instance variable does not get iniUalized cither of these ways it is left void; an :init 
method may inidalize it (sec below). 

All remaining keywords and values specified in the ;default-init-plist option to defflavor, 
diat do not inidalize instance variables and are not overridden by anything expliciUy 
specified in init-plist are then merged into init-plisi using putprop. The default init plist 
of the instantiated flavor is considered first, followed by those of all die component flavors 
in the standard order. See page 425. 

Then keywords appearing in the inil-plist but not defined with the :init-keywords option 
or the dnittable-instance-variables opdon for some component flavor are collected. If 
the :allow-other-keys option is specified with a non-nil value (either in the original init- 
plist argument or by some default init plist) then these unhandled keywords are ignored. 
If the reiurn-unhandled-keywords argument is non-nil, a list of these keywords is returned 
as the second value of instantiate-flavor. Otherwise, an error is signaled if any 
unrecognized init keywords arc present 

If the send-init-message-p argument is supplied and non-nil, an :init message is sent to the 
newly-created instance, with one argument the init-plist. get can be used to extract 
options from this propcrtylist Each flavor that needs initializadon can contribute an .init 
method by defining a daemon. 

^fhe ;init methods should not look on the init-plist for keywords that simply initialize 
instance variables (that is, keywords defined with :inittable-instance-variables rather than 
:init-keywords). 'ITie corresponding instance variables arc already set up when the ;init 
methods are called, and sometimes the keywords and their values may actually be missing 
from the init-plisi if it is more efficient not to put them on. To avoid problems, always 
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refer tu the instance variables themselves rather titan luoking for the init keywords that 
initialize them. 

rinit inil-plisl Operation on all flavor instances 

This operation is implemented on all flavor instances. Its puiposc is to cxarninc the init 
keywords and perform whatever initializations arc appropriate, init-plist is the argument 
tliat was given to instantiate-flavor, and may be passed directly to get to examine the 
value of any particular init option. 

'I'hc default definition of this operation docs nothing. However, many flavoi-s add ibefore 
and rafter daemons to it. 

tnstancep object 

Returns t if object is an instance. 'Ihis is equivalent to (typep object ’instance). 

defwrapper Macro 

This is hairy and if you don’t understand it you should skip it. 

Sometimes the way the flavor system combines the methods of different flavors (the 
daemon system) is not powerful enough. In that case defwrapper can be used to define a 
macro that expands into code tltat is wrapped around tlie invocation of the methods. This 
is best explained by an example; suppose you needed a lock locked during the processing 
of tlic :foo operation on flavor bar, which takes two arguments, and you have a lock- 
frobboz special-form that knows how to lock die lock (presumably it generates an 
unwind-protect), lock-frobboz needs to see the first argument to the operation; perhaps 
that tells it what sort of operation is going to be performed (read or write). 

(defwrapper (bar :foo) ((argl argZ) . body) 

'(lock-frobboz (self argl) 

. .body)) 

The use of the body macro-argument prevents the macro defined by defwrapper from 
knowing the exact implementation and allows several defwrapper’s from different flavors 
to be combined properly. 

Note well that the argument variables, arg1 and arg2, are not referenced with commas 
before tliem. These may look like defmacro “argument” variables, but they are not. 
Those variables arc not bound at the time tlie defwrapper-defined macro is expanded and 
the back-quoting is done; ratlier the result of that macro-expansion and back-quoting is 
code which, when a message is sent, will bind those variables to tlie arguments in the 
message as local variables of the combined method. 

Consider another example. Suppose you thought you wanted a ;before daemon, but 
found that if the argument was nil you needed to return from processing the message 
immediately, without executing the primary method. You could write a wrapper such as 
(defwrapper (bar :foo) ((argl) . body) 

'(cond ((null argl)) 

(t (print "About to do :FOO") 

. .body))) 


FS:<L.MAN>FLAVOR.TKXT.134 


8-JUN-84 



419 


I'lavor l-iMKlii)ns 


I isp M;icliinc M^iiuiui 


Suppose you need a variable for comnuinication among tlie daemons for a particular 
operation; perhaps the :after daemons need to know what the primary metliod did, and it 
is something that cannot be easily deduced from just the arguments. You might use an 
instance variable for this, or you might create a special variable which is bound during 
the processing of the operation and used free by the methods. 

(defvar *communication*) 

{defwrapper (bar :foo) (ignore .body) 

'(let (( *comniunication* nal)) 

. .body)) 

Similarly you might want a wrapper tliat puts a catch around tlie pr<Kessing of an 
operation so tliat any one of the methods could tlirow out in tlie event of an unexpected 
condition. 

Like daemon methods, wrappers work in outside-in order; when you add a defwrapper 
to a flavor built on other flavors, the new wrapper is placed outside any wrappers of the 
component flavors. However, all wrappers happen before any daemons happen. When 
the combined method is built, the calls to tlie before-daemon metliods, primary methods, 
and after-daemon methods are all placed together, and then the wrappers are wrapped 
around them. ’ITius, if a component flavor defines a wrapper, methods added by new 
flavors execute within that wrapper’s context. 

:around methods can do some of the same things that wrappers can. Sec page 439. If 
one flavor defines both a wrapper and an laround method for the same operation, the 
laround method is executed inside the wrapper. 

By careful about inserting the body into an internal lambda-expression within the 
wrapper’s code. Doing so interacts with the internals of the flavor system and requires 
knowledge of tilings not documented in the manual in order to work properly. It is much 
simpler to use an :around method instead. 

undefmethod (flavor [(ype] operation [suboperation]) Macro 

(undefmethod (flavor :before roperation)) 
removes the method created by 

(defmethod (flavor :before loperation) (args) ...) 

To remove a wrapper, use undefmethod with iwrapper as the method type. 

undefmethod is simply an interface to fundefine (see page 241) that accepts the same 
syntax as defmethod. 


If a file that used to contain a method definition is reloaded and if that method no longer 
seems to have a definition in the file, the user is asked whether to undefmethod that 
method. This may be important to enable the modified program to inherit the methods it 
is supposed to inherit If the method in question has been redefined by some other file, 
this is not done, tlie assumption being that the definition was merely moved. 
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undefflavop flavor 

Undcfincs flavor flavor. All methods of the flavor arc lost, flavor and all flavors tliat 
depend on it arc no longer valid to instantiate. 

If instances of the discarded definition exist, they continue to use that definition. 

self Variable 

When a message is sent to an object, the variable self is automatically bound to that 
object, for the benefit of methods which want to manipulate the object itself (as opposed 
to its instance variables). 

funcall-self operation arguments... 

lexpr-funcall-self operation arguments... list-of-arguments 

funcall-self is nearly equivalent to funcall with self as the first argument, funcall-self 
used to be faster, but now funcall of self is just as fast, rhcrcforc, funcall-self is 
obsolete. It should be replaced with funcall or send of self. 

likewise, lexpr-funcall-self should be replaced with use of lexpr-send to self. 

funcall-w1th-mapping-tabl0 functiot^.mapping-table &rcst arguments 

Applies function to arguments with sysiself-mapping-table bound to mapping-table. This 
is faster than binding tlic variable yourself and doing an ordinary funcall, because the 
system assumes that the mapping table you specify is tlic correct one for function to be 
run with. However, if you pass the wrong mapping table, incorrect execution will take 
place. 

This function is used in the code for combined metliods and is also useful for the user in 
:around metliods (see page 439). 

Iexpr-funcall-w1th-raapp1ng-table function mapping-table &rest arguments 

Applies function to arguments using lexpr-funcall, with sys:self-mapping-table bound to 
mapping-table. 

declare-flavop-fnstance-vaplables {flavoi) body... Macro 

Sometimes it is useful to have a function which is not itself a method, but which is to be 
called by methods and wants to be able to access the instance variables of the object self. 
The form 

(declare-flavor-instance-variables {flavor-name) 

(defun function args body...)) 

surrounds Uie function definition with a peculiar kind of declaration which makes the 
instance variables of flavor flavor-name accessible by name. Any kind of function 
definition is allowed: it does not have to use defun per se. 

If you call such a flinction when self’s value is an instance whose flavor does not include 
flavor-name as a component, it is an error. 

Cleaner than using declare-flavor-instance-variables, because it docs not involve 
putting anything around tlic function definition, is using a local declaration. Put (declare 
(:self-flavor flavorname)) as the first expression in the body of the function. For example: 
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(defun foo (a b) 

(declare (:self-flavor rayobject)) 

(+ a (♦ b speed))) 

(where speed is an instance variable of the (lavor myobject) is equivalent to 
(declare-flavor-instance-variables (myobject) 

(defun foo (a b) 

(+ a (• b speed)))) 

with-self-varlables-bound body... Specialfonn 

Within the body of this special form, all of self's instance variables are bound as specials 
to die values inside self. (Normally this is true only of those instance variables tliat arc 
specified in :special-instance-variables when self's flavor was defined.) As a result, 
inside the body you can use set. boundp and symeval, etc., freely on the instance 
variables of self. 

recomplla-flavor flavor^name &optiunal single-operation (use-old-coinbined-nwihodsi) 
(do-dependentsi) 

Updates the internal data of the flavor and any flavors that depend on it. If single- 
operation is supplied non-nil, only the methods for that operation arc changed. The 
system docs this when you define a new method that did not previously exist. If use-old- 
combined-methods is t, then the existing combined mctliod functions arc used if possible. 
New ones are generated only if the set of methods to be called has changed. This is the 
default. If use-old-combined-methods is nil, automatically-generated functions to call 
multiple methods or to contain code generated by wrappers are regenerated 
unconditionally. If do-dependents is nil, only the specific flavor you specified is 
recompiled. Normally all flavors that depend on it are also recompiled. 

recompile-flavor affects only flavors that have already been compiled. Typically this 
means it affects flavors that have been instantiated, but does not bother with mixins (see 
page 431). 

si :*dont-r0compne-flavops* Variable 

If this variable is non-nil, automatic recompilation of combined methods is turned off. 

If you wish to make several changes each of which will cause recompilation of the same 
combined methods, you can use this variable to speed things up by making the 
recompilations happen only once. Set the variable to t, make your changes, and then set 
the variable back to nil. Then use recompile-flavor to recompile whichever combined 
methods need it. For example: 

(setq si:•dont-recompile-flavors* t) 

(undefmethod (tv:sheet :after :bar)) 

(defmethod (tv:sheet cbefore :bar) ...) 

(setq si:*dont-recompile-flavors* nil) 

(recompile-flavor ’tv:sheet :bar) 

tv’sheet has very many dependents; recompile-flavor even once takes painfully long. It’s 
nice to avoid spending the time twice. 
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compile-flavor-methods Jlawr... Macro 

The form (compile-flavor-methods flavoMiamc-1 flavor-name-2...), placed in a flic to be 
compiled, directs tlic compiler to include tlic automatically-generated combined mctliods 
for the named flavors in tlic resulting Qh'ASI. file, provided all of the necessary flavor 
definitions have been made. ITirthcrmorc, all internal daut structures needed to instantiate 
the flavor will be computed when tlic Ql'ASl. file is loaded rather tlian waiting until the 
first attempt to insUiiitiatc it. 

This means that tlic combined mcUiods get compiled at compile time and the data 
structures get generated at load time, ratlicr than both things happening at run time. ITiis 
is a very good thing, since if the tlic compiler must be invoked at run time, tlic program 
will be slow tlic first time it is run. ( The compiler must be called in any ease If 
incompatible changes have been made, such as addition or deletion of mctliods tliat must 
be called by a combined mclliod.) 

You should only use compile-flavor-methods for flavors that arc going to be 
instantiated, l-'or a flavor tiiat is never to be instantiated (that is, a flavor that only serves 
to be a component of otlicr flavors that actually do get instantiated), it is a complete 
waste of time, except in the unusual ease where those otlicr flavors can all inherit the 
combined methods of this flavor instead of each one having its own copy of a combined 
mcdiod which happens to be identical to the others. In this unusual case, you should use 
the labstract-flavor option in defflavor (page 428). 

The compile-flavor-methods forms should be compiled after all of the information 
needed to create the combined mctliods is available. You should put tlicsc forms after all 
of tlic definitions of all relevant flavors, wrappers, and methods of all components of the 
flavors mentioned. 

The methods used by compile-flavor-methods to form tlic combined methods that go in 
tlic QFASL file are all those present in the file being compiled and all those defined in 
the Lisp world. 

When a compile-flavor-methods form is seen by the intcipreter, the combined methods 
are compiled and the internal data structures are generated. 

get-handler-for object operation 

Given an object and an operation, Uiis returns the object’s mctliod for that operation, or 
nil if it has none. When object is an instance of a flavor, tliis function can be useful to 
find which of that flavor's components supplies tlic method. If you get back a combined 
method, you can use the Meta-X List Combined Methods editor command (page 444) to 
find out what it docs. 

This is related to Uic :handler function spec (see section 11.2, page 223). 

It is preferable to use the generic operation :get-handler-for. 
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flavor-allows-lnlt-keyword-p favor-name keyword 

Rclurns non-nil if llic flavor named favor-name allows keyword in llic inil options when it 
is instantiated, or nil if it does not. The non-nil value is the name of Uie component 
flavor that contributes tlic support of that keyword. 

si:flavor-an-allowed-1n1t-keywords favor-name 

Returns a list of all the init keywords that may be used in instantiating/r/voz-Hfl/ne. 

symeval-1n-1nstance insianee symbol &optional no-error-p 

Returns the value of die instance variable symbol inside instance. If there is no such 
instance variable, an error is signaled, unless no-error-p is non-nil in which case nil is 
returned. 

set-ln-lnstance instance symbol value 

Sets tlie value of the instance variable symbol inside instance to value. If there is no such 
instance variable, an error is signaled, 

1ocate-1n-Instance instance symbol 

Returns a locative pointer to the cell inside instance which holds the value of the instance 
variable named symbol. 


descpibe-tlavor favor-name 

Prints descriptive information about a flavor; it is self-explanatory. An important thing it 
tells you that can be hard to figure out yourself is the combined list of component flavors; 
this list is what is printed after the phrase ‘and directly or indirectly depends on’. 

si: *flavor-compilat1ons* Variable 

Contains a history of when the flavor mechanism invoked the compiler. It is a list; 
elements toward the front of the list represent more recent compilations. Elements are 
typically of the form 

(fimclion-spec pathname) 

where the function spec starts with ;method and has a method type of :Gombined. 

You may setq this variable to nil at any time; for instance before loading some files that 
you suspect may have missing or obsolete compile-flavor-methods in them. 


sys:unclaimed-message (error) Condition 

This condition is signaled whenever a flavor instance is sent a message whose operation it 
does not handle. The condition instance supports these operations; 

;object The flavor instance that received the message. 

:operation The operation that was not handled. 

:arguments The list of arguments to that operation 
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21.8 Dcfflavor Options 

There arc quite a few options to defflavor. 'I’hcy arc all described here, although st)mc arc 
for very specialized purposes and not of interest to most users. Kach option can be written in two 
forms; citJicr the keyword by itself, or a list of the keyword and arguments to that keyword. 

Several of these options declare things about insUincc variables, nicsc options can be given 
with arguments which arc instance variables, or without any arguments in which case they refer to 
all of the instance variables listed at the top of the defflavor. This is not necessarily all the 
instance variables of tlic component flavors, just the ones mentioned in this flavor's defflavor. 
When arguments arc given, tltcy must be instance variables that were listed at tlic top of the 
defflavor: otherwise tlicy arc assumed to be misspelled and an error is signaled. It is legal to 
declare things about instance variables inherited from a component flavor, but to do so you must 
list these instance variables explicitly in the instance variable list at the top of tlie defflavor. 

:gettable-instance-variables 

Knablcs automatic generation of methods for getting the values of instance variables. The 
operation name is the name of tlie variable, in the keyword package (i.c. it has a colon in 
front of it). 

Note that there is nothing special about these methods; you could easily define them 
yourself. I'his option generates tlicm automatically to save you the trouble of writing out 
a lot of very simple method definitions. /The same is tnie of methods defined by the 
isettable-instance-variables option.) If you define a mctliod for the same operation 
name as one of the automatically generated metliods, tlie explicit definition overrides the 
automatic one. 

:settable-instance-variables 

Enables automatic generation of methods for setting the values of instance variables. ITie 
operation name is ':set-’ followed by the name of the variable. All settable instance 
variables are also automatically made gettable and inittable. (See the note in the 
description of the :gettable-instance-variables option, above.) 

In addition, :case methods are generated for the :set operation with suboperations taken 
from tlie names of the variables, so that :set can be used to set them. 

:in ittable - instance-variables 

'fhe instance variables listed as arguments, or all instance variables listed in this defflavor 
if the keyword is given alone, arc made inillable. ITiis means that they can be initialized 
through use of a keyword (a colon followed by the name of the variable) as an init-option 
argument to make-instance. 

:special - instance-variables 

'The instance variables listed as arguments, or all instance variables listed in this defflavor 
if the keyword is given alone, will be bound dynamically when handling messages. (By 
default, instance variables arc bound lexically with tlie scope being the method.) You must 
do this to any insumce variables that you wish to be accessible Uirough symeval. set, 
boundp and makunbound, since they see only dynamic bindings. 
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This should also be done for any instance variables that iire declared globally special. If 
you omit this, the flavor system docs it for you automatically when you instantiate the 
flavor, and gives you a warning to remind you to fix the defflavor. 

:init-keywords 

The arguments are declared to be valid keywords to use in instantiate^flavor when 
creating an instance of this flavor (or any flavor containing it). I'he system uses this for 
error-checking: before the system sends the :init message, it makes sure that all the 
keywords in the init-plist are either inittable instance variables or elements of this list. If 
any is not recognized, an error is signaled. When you write a :init metliod that accepts 
some keywords, they should be listed in the :init-keywords option of the flavor. 

If ;allow-other-keys is used as an init keyword with a non-nil value, this error check is 
suppressed. Then unrecognized keywords are simply ignored. 

:default-init-plist 

The arguments arc alternating keywords and value forms, like a property list When the 
flavor is instantiated, tltcsc properties and values are put into the init-plist unless already 
present 'I’his allows one component flavor to default an option to another component 
flavor. The value forms arc only evaluated when and if they are used. For example, 

(:default-init-plist :frob-array 

(make-array 100)) 

would provide a default “frob array" for any instance for which the user did not provide 
one explicitly. 

(:default-init-plist :allow-other-keys t) 
prevents errors for unhandlcd init keywords in all instantiation of this flavor and other 
flavors that depend on it. 

•.required - init-keywords 

The arguments are init keywords which are to be required each time this flavor (or any 
flavor containing it) is instantiated. An error is signaled if any required init keyword is 
missing. 

:required - instance-variables 

Declares that any flavor incorporating this one that is instantiated into an object must 
contain the specified instance variables. An error occurs if there is an attempt to 
instantiate a flavor that incorporates this one if it does not have these in its set of instance 
variables. Note that this option is not one of those that checks the spelling of its 
arguments in the way described at the start of this section (if it did, it would be useless). 

Required instance variables may be freely accessed by methods just like normal instance 
variables. The difference between listing instance variables here and listing them at the 
front of the defflavor is that the latter declares that this flavor “owns" those variables and 
accepts responsibility for initializing them, while the former declares that this flavor 
depends on those variables but tliat some other flavor must be provided to manage them 
and whatever features they imply. 

:required-methods 

The arguments are names of operations that any flavor incorporating this one must handle. 
An error occurs if there is an attempt to instantiate such a flavor and it is lacking a 
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method for one of these operations. Typically this option appears in the defflavor for a 
base flavor (see page 431). Usually this is used when a base flavor docs a (send self ...) 
to send itself a message that is not handled by the base flavor itself; the idea is Uiat the 
base flavor will not be instantiated alone, but only with other components (mixins) that do 
■ handle the mcs.sagc. This keyword allows the error of having no handler for the message 
to be detected when tlic flavor instantiated or when compile-flavor-methods is done, 
rather than when tlic missing operation is used. 

irequired-flavors 

The arguments arc names of flavors that any flavor incorporating tltis one must include as 
components, directly or indirectly. The diflcrcncc between declaring flavors as required 
and listing tlicm directly as components at the top of the defflavor is that declaring 
flavors to be required does not make any commitments about where diosc flavors will 
appear in die ordered list of components: that is left up to whoever docs specify them as 
components. Ihc purpose of declaring a flavor to be required is to allow instance 
variables declared by diat flavor to be accessed. It also provides error checking: an 
attempt to insumtiatc a flavor that does not include the required flavors as components 
signals an error. Compare diis with required-methods and :required-instance- 
variables. 


For an example of die use of required flavors, consider the ship example given earlier, 
and suppose we want to define a relativity-mixin which increases the mass dependent on 
the speed. We might write, 

(defflavor relativity-mixin () (moying-object)) 

(defmethod (relativity-mixin :mass) () 

(//mass (sqrt (- 1 (^ (// (send self :speed) 

*speed-of-light*) 

2 ))))) 

but this would lose because any flavor that had relativity-mixin as a component would get 
moving-object right after it in its component list. As a base flavor, moving-object 
should be last in the list of components so that other components mixed in can replace its 
methods and so diat daemon methods combine in the right order, relativity-mixin has no 
business changing the order in which flavors are combined, which should be under the 
control of its caller. For example, 

(defflavor starship () 

(relativity-mixin long-distance-mixin ship)) 
puts moving-object last (inheriting it from ship). 


So instead of the definition above we write, 

(defflavor relativity-mixin () () 

(irequired-flavors moving-object)) 

which allows relativity-mixin's methods to access moving-object instance variables such as 
mass (the rest mass), but docs not specify any place for moving-object in the list of 
components. 


It is very common to specify the base flavor of a mixin with the irequired-flavors option 
in this way. 


linciuded-flavors 

The arguments are names of flavors to be included in this flavor. The difference between 
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declaring flavors here and declaring tliem at the top of the defflavor is dial when 
component flavors are combined, if an included flavor is not specified as a nornial 
component, it is inserted into tlie list of components immediately after tlte last component 
to include it. 'Hius included flavors act like defaults. 'I'hc important Uiing is that if an 
included flavor is specified as a component, its position in the list of components is 
completely controlled by tliat specification, independently of where the fltivor that includes 
it appears in tlic lisL 

:included-flavors and irequired-flavors arc used in similar ways; it would have been 
reasonable to use :included -flavors in die relativity-mixin example above. The diflrcrcnce 
is diat when a flavor is required but not given as a nomial component, an error is 
signaled, but when a flavor is included but not given as a normal component, it is 
automatically inserted into die list of components at a reasonable place. 

:no-vanilla-flavor . „ • • i j j 

Nonnally when a flavor is insUintiated, the special flavor si;vanitla-flavor is included 

automatically at the end of its list of components. 'I’hc vanilla flavor provides some 
default methods for the standard operations which all objects arc supposed to understand. 
These include :print-self, :describe, :which-operations, and several other operations. 
Sec section 21.10, page 432. 

If any component of a flavor specifics the :no-vanilla-flavor option, then si:vanilla-flavor 
is not included in that flavor, lliis option should not be used casually. 

:default-handler , 

I'he argument is the name of a function that is to be called to handle any operation tor 
which there is no method. Its arguments are die arguments of the send which invoked 
the operation, including the operation name as the first argument. Whatever values the 
default handler returns are the values of the operation. 

Default handlers can be inherited from component flavors. If a flavor has no default 
handler, any operation for which there is no method signals a sys'.uhclaimed-message 

error. 

:ordered-inst8uice-variables 

This option is mostly for esoteric internal system uses. The arguments are names of 
instance variables which must appear first (and in this order) in all instances of this flavor, 
or any flavor depending on this flavor. This is used for instance variables that are 
specially known about by microcode, and also in connection with the :outside- 
accessible-instance-variables option. If the keyword is given alone, the arguments 
default to the list of instance variables given at the top of this defflavor. 

Removing any of the :ordered-instance-variables, or changing their positions in the list, 
requires that you recompile all methods that use any of the affected instance variables. 

:outside-accessible-instance-variables • p u- 

The arguments are instance variables which are to be accessible from outside ^ of this 
flavor’s mediods. A macro (actually a subst) is defined which takes an object of this flavor 
as an argument and returns the value of the instance variable; setf may be used to set 
the value of the instance variable. The name of die macro is the name of the flavor 
concatenated with a hyphen and the name of the instance variable. These macros are 
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similar to llic accessor macros created by defstruct (see chtipter 20, page 372.) 

This feature works in two different ways, depending on whether the instance variable has 
been declared to have a fixed slot in all instances, via the :ordered-instance-variables 
option. 

If the variable is not ordered, the position of its value cell in the instance must be 
computed at run time. This takes noticeable time, although less tlum tictually sending a 
message would take. An error is signaled if the argument to the accessor macro is not an 
instance or is an instance Uiat does not have an instance variable with the appropriate 
name. However, there is no error check tliat the flavor of the instance is the flavor the 
accessor macro was defined for, or a flavor built upon that flavor. This error check would 
be too expensive. 

If the variable is ordered, the compiler compiles a call to the accessor macro into a 
subprimitivc which simply accesses tltat variable’s assigned slot by number. 'ITiis 
subpriinitive is only tltrcc or four times slower than car. 1’hc only error-checking 
perfonned is to make sure that die argument is really an instance and is really big enough 
to contain tliat slot. There is no check that the accessed slot really belongs to an instance 
variable of the appropriate name. 

.accessor-prefix 

Normally the accessor macro created by tlie :outside-accessible-instance-variables 
option to access the flavor /s instance variable v is named /v. Specifying (:accessor- 
prefix get$) causes it to be named get$v instead. 

:alias-flavor 

Marks this flavor as being an alias for another flavor. This flavor should have only one 
component, which is the flavor it is an alias for, and no instance variables or other 
options. No methods should be defined for it. 

The effect of the ralias-flavor option is that an attempt to instantiate this flavor actually 
produces an instance of tlie other flavor. Without this option, it would make an instance 
of this flavor, which might behave identically to an instance of the other flavor. :alias- 
flavor eliminates the need for separate mapping tables, method tables, etc. for this flavor, 
which becomes truly just another name for its component flavor. 

The alias flavor and its base flavor are also equivalent when used as an argument of 
subtypep or as the second argument of typep; however, if the alias status of a flavor is 
changed, you must recompile any code which uses it as the second argument to typep in 
order for such code to function. 

:alias-flavor is mainly useful for changing a flavor’s name gracefully. 

:abstract-flavor 

ITiis option marks the flavor as one that is not supposed to be instantiated (that is, is 
supposed to be used only as a component of other flavors). An attempt to instantiate the 
flavor signals an error. 
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It is sometimes useful to do compile-flavor-methods on a flavor Uiat is not going to be 
instantiated, if the combined methods for this flavor will be inherited and shared by many 
others. :abstract-flavor tells compile-flavor-methods not to complain about missing 
required flavors, metltods or insumce variables. Presumably the flavors tliat depend on 
this one and actually arc instantiated will supply what is lacking. 

:method-combination 

Specifics tlic mctliod combination style to be used for certain operations. Hach argument 
to this option is a list {style order operation! operation2...). operation I, operation!, etc. 
arc names of operations whose methods arc to be combined in die declared fashion, style 
is a keyword tliat specifics a style df combination: see section 21.11, page 433. order is a 
keyword whose interpretation is up to style', typically it is either :base-flavor-first or 
:base-flavor-last. 

Any component of a flavor may specify the type of method combination to be used for a 
particular operation. If no component specifies a style of method combination, then the 
default style is used, namely rdaemon. If more than one component of a flavor specifies 
the combination style for a given operation, then they must agree oh the specification, or 
else an error is signaled. 

:instance-area-function 

riic argument is the name of a function to be used when this flavor is instantiated, to 
determine which area to create the new instance in. Use a function name rather than an 
explicit lambda expression. 

(: instance-area-function function-name) 

When the instance area function is called, it is given the init plist as an argument, and 
should return an area number or nil to use the default. Init keyword values can be 
accessed using get on the init plisL 

Instance area functions can be inherited from component flavors. If a flavor does not 
have or inherit an instance area function, its instances are created in default-cons-area. 

:instantiation-flavor-function 

You can define a flavor foo so that, when you try to instantiate it, it calls a function to 
decide what flavor it should really instantiate (not necessarily foo). Tliis is done by giving 
foo an instantiation flavor function: 

(:instantiation-flavop-function Junction-name) 

When (make-instance ’foo keyword-args,..) is done, the instandation flavor function is 
called with two arguments: the flavor name specified (foo in this case) and the init plist 
(the list of keyword args). It should return the name of the flavor that should actually be 
instantiated. 

Note that the instantiation flavor function applies only to tlie flavor it is specified for. It 
is not inherited by dependent flavors. 

.run - time - alternatives 
;mixture 

A run-timc-alternadve flavor defines a collccdon of similar flavors, all built on the same 
base flavor but having various mixins as well. Instantiation chooses a flavor of the 
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collection at run time based on the init keywords specified, using an auloraatically 
generated instantiation (lavor function. 

A simple example would be 

(defflavor foo () (basic-foo) 

(:run-time-alternatives 
(:big big-foo-mixin)) 

{:init-keywords :big)) 

Iben (make-instance 'foo :big t) makes an instance of a flavor whose components arc 
big-foo-mixin as well as foo. But (make-instance ’foo) or (make-instance ’foo :big 
nil) makes an instance of foo itself, fhe clause (:big big-foo-mixin) in tlic :run-time- 
alternatives says to incorpt)ratc big-foo-mixin if :big’s value is t, but not if it is nil. 

There may be several clauses in die :run-time-alternatives. Hach one is processed 
independently. 'ITius, two keywords ;big and :wide could independently control two 
mixins, giving four possibilities. 

(defflavor foo () (basic-foo) 

(:run-time-alternatives 
(:big big-foo-mixin) 

(;wide wide-foo-mixin)) 

(:init-keywords :big)) 

It is possible to test for values other than t and nil. The clause 
(:size (:big big-foo-mixin) 

(:small small-foo-mixin) 

(ni 1 ni 1)) 

allows tlic value for the keyword :size to be :big, :small or nil (or omitted). If it is nil 
or omitted, no mixin is used (that’s what the second nil means). If it is :big or .’small, 
an appropriate mixin is used. I’his kind of clause is distinguished from the simpler kind 
by having a list as its second clement. The values to check for can be anything, but eq 
is used to compare them. 

The value of one keyword can control the interpretation of others by nesting clauses 
within clauses. If an alternative has more than two elements, tlie additional elements are 
subclauses which are considered only if that alternative is selected. For example, the 
clause 

(:etheria1 (t etherial-mixin) 

(ni1 ni 1 

(:size (:big big-foo-mixin) 

(:smal1 small-foo-mixin) 

(nil nil)))) 

says to consider the :size keyword only if :etherial is nil. 

;mixture is synonymous with :run-time-alternatives. It exists for compatibility with 
Symbolics systems. 

:documentation 

Specifics the documentation string for the flavor definition, which is made accessible 
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through (documentation flavoruame ’flavor). 

This documentation can be viewed with the describe-flavor function (see page 423) or 
the editor’s Meta-X Describe Flavor command (sec page 443). 

Previously this option expected two arguments, a keyword and a string. I he keyword was 
intended to classify the flavor as a base flavor, mixin or combination. Hut no way was 
found for this classification to serve a useful purpose. Keyword are still accepted but no 
longer recommended for use. 

21.9 Flavor Families 

I’he following organization conventions are recommended for programs that use flavors. 

A base flavor is a flavor tliat defines a whole family of related flavors, all of which have that 
base flavor as a component. Typically die base flavor includes things relevant to the whole family, 
such as instance variables, required-methods and :rec|uired-instance-variables declarations, 
default metltods for certain operations. :method-combination declarations, and dcKumentation on 
the general protocols and conventions of the family. Some base flavors are complete and can be 
insuintiated, but most arc not instantiatablc and merely serve as a base upon which to build other 
flavors. 'The base flavor for the foo family is often named basic-/>o. 

A mixin flavor is a flavor that defines one particular feature of an object. A mixin cannot be 
instantiated, because it is not a complete description. Bach module or feature of a program is 
defined as a separate mixin; a usable flavor can be constructed by choosing the mixins for the 
desired characteristics and combining them, along vvith the appropriate base flavor. By organizing 
your flavors this way, you keep separate features in separate flavors, and you can pick and choose 
among them. Sometimes the order of combining mixins docs not matter, but often it docs, 
because the order of flavor combination controls the order in which daemons arc invoked and 
wrappers are wrapped. Such order dependencies should be documented as part of the conventions 
of the appropriate family of flavors. A mixin flavor that provides the mumble feature is often 
named wumWc-mixin. 

If you arc writing a program that uses someone else’s facility to do something, using that 
facility’s flavors and methods, your program may still define its own flavors, in a simple way. 
The facility provides a base flavor and a set of mixins: the caller can combine these in various 
ways depending on exactly what it wants, since the facility probably docs not provide all possible 
useful combinations. Even if your private flavor has exactly the same components as a pre¬ 
existing flavor, it can still be useful since you can use its :default-init-plist (sec page 425) to 
select options of its component flavors and you can define one or two methods to customize it 
“just a little”. 
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21.10 Vanilla Flavor 

I'hc operations described in this section arc a suindard proUKol, which all message-receiving 

objects arc assumed to understand. The standard metltods dial implement tliis protocol are 

automatically supplied by the flavor system unless tlic user specifically tells it not to do so. 'ITicsc 

methods arc associated with the flavor si:vanitla-flavor: 

s1: vanina-f lavop Flavor 

Unless you specify otherwise (with tlic :no-vanilla-flavor option to defflavor), every 
flavor includes tlie “vanilla" flavor, which has no instance variables but provides some 
basic useful methods. 

:pr1nt-self stream prindepth escape-p Operation 

The object should output its printed-representation to a stream. The printer sends tJiis 
message when it encounters an instance or an entity. 1'he arguments arc tlic stream, the 
current depth in list-structure (for comparison with prinlevel), and whether escaping is 
enabled (a copy of the value of ‘print-escape*; see page 514). si:vanilla-flavor ignores 
die last two arguments and prints something \\Yc # <Jlavor-name octaI-address>. '1'he 
flavor-name tells you what type of object it is and the octal-address allows you to tell 
different objects apart (provided the garbage collector doesn’t move them behind your 
back). 

: describe Operation 

The object should describe itself, printing a description onto the ‘standard-output* 
stream. 'I'he describe function sends this message when it encounters an instance. 
si;vanilla-flavor outputs in a reasonable format the object, die name of its flavor, and the 
names and values of its instance-variables. 

:set keyword value Operation 

'I'he object should set the internal value specified by keyword to the new value value. For 
flavor instances, the :set operation uses :case method combination, and a method is 
generated automatically to set each settable instance variable, with keyword being the 
variable’s name as a keyword. 

:wh1ch-operat1ons Operation 

I'he object should return a list of the operations it can handle. si:vanilla-flavor generates 
the list once per flavor and remembers it, minimizing consing and compute-time. If the 
set of operations handled is changed, diis list is regenerated the next time someone asks 
for it. 

:operat1on-handl0d-p operation Operation 

operation is an operation name. The object should return t if it has a handler for the 
specified operation, nil if it does not. 

:g0t-hand1er-for operation Operation 

operation is an operation name. 'The object should return the mediod it uses to handle 

operation. If it has no handler for that operation, it should return nil. 'This is like the 
get-handfer-for function (see page 422), but, of course, you can use it only on objects 
known to accept messages. 
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:send-if-handles operation &resl arguments Operation 

operation is an operation name and arguments is a list of arguments for tlic operation. If 
the object handles die operation, it should send itself a message with that operation and 
arguments, and return whatever values that messiigc returns. If it doesn’t handle the 
operation it should just return nil. 

:eval-1nside-yourself form Operation 

The argument is a form that is evaluated in an environment in which special variables 
with the mimes of the insuince variables aic bound to the values of tlic®insUincc variables. 
It works to setq one of tlicsc special variables; tlic instance variable is modified. This is 
intended to be used mainly for debugging. 

:funcan-1ns1de-yourself function &rcst args Operation 

function is applied to args in an environment in which special variables with the names of 
the insuince variables are bound to the values of tlie instance variables. It works to setq 
one of these special variables; the instance variable is modified. T his is a way of allowing 
callers to provide actions to be performed in an environment set up by the instance. 

: break Operation 

break is called in an environment in which special variables with the names of the 
instance variables are bound to the values of the instance variables. 

21.11 Method Combination 

When a flavor has or inherits more than one mctJiod for an operation, they must be called in 
a specific sequence. Tlie flavor system creates a function called a combined method which calls all 
the user-specified methods in the proper order. Invocation of tlic operation actually calls the 
combined method, which is responsible for calling the others. 

For example, if the flavor foo has components and methods as follows: 

(defflavor foo () (foo-mixin foo-base)) 

(defflavor foo-mixin () (bar-mixin)) 

(defmethod (fob :before :hack) ...) 

(defmethod (foo rafter rhack) ,.,) 

/ 

(defmethod (foo-mixin rbefore rhack) ...) 

(defmethod (foo-mixin rafter rhack) ...) 

(defmethod (bar-mixin rbefore rhack) ...) 

(defmethod (bar-mixin rhack) ...) 

(defmethod (foo-base rhack) ...) 

(defmethod (foo-base rafter rhack) ...) 

then the combined method generated looks like this (ignoring many important details not related 
to this issue): 
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(defmethod (foo ;combined :hack) (Snest args) 

(apply #’{:niethod foo :before ;hack) args) 

(apply #’(:method foo-inixin :before :hack) args) 
(apply #’(.-method bar-mixin :before :hack) args) 
(multiple-value-progl 

(apply #’(;method bar-mixin :hack) args) 
(apply /^’(rmethod foo-base :after :hack) args) 
(apply #’(:method foo-mixin :after :hack) args) 
(apply #’(rmethod foo :after :hack) args))). 


This example shows the default style of metliod combination, tlic one described in the 
introductory parts of tliis chapter, called :daemon combination, Hach style of method 
combination defines which method types it allow.s, and what tliey mean. ;daemon combination 
accepts method types :before and :after, in addition to untyped methods; then it creates a 
combined metliod which calls all die :before methods, only one of the untyped methods, and 
then all the :after methods, returning tlic value of die untyped method. 'Hie combined method is 
constructed by a function much like a macro's expander function, and the precise technique used 
to create the combined mediod is what gives :before and :after dicir meaning. 


Note that the rbefore mediods arc called in the order foo, foo-mixin, bar-mixin and foo- 
base. (foo-base does not have a :before method, but if it had one that one would be last) 
'Ihis is the standard ordering of die components of die flavor foo (sec page 412); since it puts 
the base flavor last, it is called :base-flavor-last ordering. The ;after methods arc called in the 
opposite order, in which the base flavor comes first. This is called ;base-flavor-first ordering. 


Only one of the untyped methods is used; it is the one diat comes first in :base-flavor-last 
ordering. An untyped mediod used in this way is called a primary method. 

Other styles of method combination define their own method types and have their own ways 
of combining them. Use of another style of method combination is requested with the :method- 
combination option to defflavor (sec page 429). Here is an example which uses :list method 
combination, a style of combination that allows :list methods and untyped methods: 
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(defflavor foo () (foo-mixin foo-base)) 

(defflavor foo-mixin () (bar-mixin)) 

(defflavor foo-base {) () 

(:met.hod-combination (:list :base-fiavor-last :w1n))) 

(defmethod (foo :list :win) ...) 

(defmethod (foo :win) . ..) 

(defmethod (foo-mixin :list :win) ...) 

(defmethod (bar-mixin :iist :win) ...) 

(defmethod (bar-mixin :win) ...) 

(defmethod (foo-base :win) ...) 

yielding the combined method 

(defmethod (foo rcombined twin) (&rest args) 

(list 

(apply #’(:method foo :list ;win) args) 

(apply /^’(:method foo-mixin :list ;win) args) 

(apply #’(:method bar-mixin :list ;win) args) 

(apply #’(:method foo twin) args) 

(apply #’(:method bar-mixin twin) args) 

(apply #’(tmethod foo-base twin) args))) 

ITie :method-combination option in tlie defflavor for foo-base causes :list method 
combination to be used for the :win operation on all flavors tliat have foo-base as a component, 
including foo. The result is a combined method which calls all the methods, including all the 
untyped methods rather than just one, and makes a list of the values they return. All the :list 
methods are called first, followed by all the untyped methods: and within each type, the :base- 
flavor-last ordering is used as specified. If the ;method-combination option said :base-flavor- 
first, the relative order of the :list methods would be reversed, and so would the untyped 
methods, but tlie :list methods would still be called before the untyped ones. :base-flavor-last 
is more often right, since it means that foo’s own methods are called first and si:vanilla-flavor’s 
mctliods (if it has any) are called last 

A few specific method types, such as ;default and :around, have standard meanings 
independent of the style of method combination, and can be used with any style. ITiey are 
described in a table below. 

Here are the standardly defined method combination styles. 

.’daemon The default style of method combination. All the ibefore methods are called, 
then the primary (untyped) method for the outermost flavor that has one is called, 
then all the :after methods are called. The value returned is the value of the 
primary method. 

:daemon-with-or 

Like the :daemon method combination style, except that the primary method is 


PS:<L.MAN>FLAVOR.TBXT.134 


8-JUN-84 




Molliod Comiiinalion 


436 


:daemon 

idaemon 


:progn 

:or 

:and 

.append 


l.isp Machine Manual 


wrapped in an ;or special form with all :or mcUiods. Multiple values can be 
returned from the primary method, but not from the :or methods (as in the or 
special form). This produces code like the following in combined mctliods: 

(progn (foo-before-method) 

(multiple-value-progl 
(or (foo-or-method) 

(foo-primary-inethod)) 

(f 00 -after-method))) 

This is useful primarily for flavors in which a mixin introduces an alternative to 
the primary method. H;ich :or method gets a chance to run before the primary 
inetJiod and to decide whether the primary method should bo run or not; if any 
:or mctliod returns a non-nil value, the primary mctliod is not run (nor arc the 
rest of tlie :or metliods). Note tliat the ordering of the combination of the :or 
mctliods is controlled by tlic order keyword in die :method-Combination option. 

with-and 

Like :daemon-with-or except that it combines :and methods in an and special 
form. ITic primary mcdiod is run only if all of die :and mcdiods return non-nil 
values. 

with-override 

Like the rdaemon method combination style, except an or special form is 
wrapped around the entire combiilcd method with all :override typed methods 
before die combined method. This differs from :daemon-with-or in diat the 
:before and :after daemons arc run only if none of die :override methods returns 
non-nil. The combined mcdiod looks something like this: 

(or (foo-override-method) 

(progn (foo-before-method) 

(foo-primary-method) 

(foo-after-method))) 

Calls all the methods inside a progn special form. Only untyped and :progn 
methods are allowed. The combined method calls all the :progn mcdiods and 
then all the untyped methods. The result of the combined method is whatever the 
last of die methods returns. 

Calls all the methods inside an or special form. ITiis means that each of the 
mediods is called in turn. Only untyped methods and :or methods arc allowed; 
the :or methods arc called first. If a method returns a non-nil value, that value is 
returned and none of die rest of the methods are called; otherwise, the next 
method is called. In other words, each method is given a chance to handle the 
message; if it doesn’t want to handle the message, it can return nil, and the next 
method gets a chance to try. 

Calls all the mediods inside an and special form. Only untyped methods and 
:and mcdiods are allowed. The basic idea is much like :or; sec above. 

Calls all the methods and appends the values together. Only untyped methods 
and .'append methods are allowed; the :append methods arc called first. 
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:nconc 

:list 

:inverse-list 

:pass-on 


:case 


Calls all Uic methods and nconc’s tlic values together. Only untyped methods 
and :nconc methods arc allowed, etc. 

Calls all die methods and returns a list of Uieir returned values. Only untyped 
mediods and :list mcdiods are allowed, etc. 

Calls each mediod with one argument; diese argtiments are successive elements of 
the list diat is die sole argument to die operation. Returns no particular value. 
Only untyped methods and :inverse-list methods are allowed, etc. 

If die result of a :list-combined operation is sent back with an linverse'-list- 
combined operation, with die same ordering and with corresponding mediod 
definitions, each component flavor receives the value diat came from diat flavor. 

Calls each mediod on die values returned by die preceeding one. 'ITie values 
returned by die combined method are those of the outemiost call. 'ITie format of 
die declaration in the defflavor is: 

{:method-combination (:pass-on (ordering . argUst)) 

. operation-names) 

where ordering is :base-flavor-first or :base-flavor-last. arglist may include the 
&aux and &optional keywords. 

Only untyped methods and :pass-on methods are allowed, llie :pass-on 
methods are called first 

With :case method combination, the combined method automatically does a 
selectq dispatch on the first argument of the operation, known as the 
suboperation. Methods of type :case can be used, and each one specifies one 
suboperation that it applies to. If no :case method matches the suboperation, the 
primary method, if any, is called. 

Example: 

(defflavor foo (a b) () 

{imethod-combination (rcase :base-f1avor-last twin))) 

This method handles (send a-foo :win :a): ' 

(defmethod (foo :case twin :a) () 

a) 

This method handles (send a-foo :win :a*b): 

(defmethod (foo tease twin ta*b) () 

(• a b)) 

This method handles (send a-foo twin :something-else): 

(defmethod (foo twin) (suboperation) 

(list ’something-random suboperation)) 

tease methods are unusual in that one flavor can have many tease methods for 
the same operation, as long as they are for different suboperations. 
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I'hc siibopcrations :which-operations, :operation-handled-p. :send-if-handles 
and :get-handler-for are all handled automatically based on die collection of 
:case mciliods dial arc present. 

Methods of type :or arc also allowed. They arc called just before the primary 
method, and if one of diem returns a non-nil value, that is die value of die 
operation, and no more methods arc called. 

Here is a uiblc of all the mediod types rccogni/.cd by die standard styles of method 
combination. 

(no type) If no type is given to defmethod. a primary method is created. This is the most 
common type of method. 

ibefore 

:after Used for die bcforc-dacmon and after-daemon mcdiods used by :daemon method 

combination. 

;default if there are no untyped methods among any of the flavors being combined, then 

the :default methods (if any) arc treated as if diey were untyped. If there are any 
untyped methods, the :default methods are ignored. 

Typically a base-flavor (see page 431) defines some default methods for certain of 
the operations understood by its family. When using the default kind of method 
combination these default methods are suppressed if another component provides a 
primary method. 

:or 

:and Used for :daemon-with-or and tdaemon-with-and method combination. The 

:or methods are wrapped in an or, or tlie :and methods are wrapped in an and, 
together with the primary method, between the :before and :after methods. 

toverride Allows the features of :or method combination to be used together with daemons. 

If you specify :daemon-with-override method combination, you may use 
•.override methods. The :override methods are executed first, undl one of them 
returns non-nil. If this happens, that method’s value(s) are returned and no more 
methods are used. If all the '.override methods return nil, the :before, primary 
and :after methods are executed as usual. 

In typical usages of this feature, the :override method usually returns nil and does 
nothing, but in exceptional circumstances it takes over the handling of the 
operation. 

:or, :and, :progn, :list. :inverse-list, pass-on, rappend, :nconc. 

Each of these methods types is allowed in the method combination style of the 
same name. In those mctliod combination styles, these typed methods work just 
like untyped ones, but all the typed methods are called before all the untyped 
ones. 

;case :case methods are used by :case method combination. 

These method types can be used with any method combination style; they have standard 
meanings independent of the method combination style being used. 
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:around An raround mctliod is able to control when, whether and how the remaining 
methods arc executed. It is given a continuation that is a function that will 
execute tlic remaining mctliods, and has complete responsibility for calling it or 
not, and deciding what arguments to give it. Kor tlic simplest behavior, the 
arguments should be tlic operation name and operation arguments tliat the 
laround mctltod itself received; but sometimes tlic whole purpose of the :around 
mctliod is to modify tlic arguments before tlic remaining mctliods see them. 

fhe raround method receives three special arguments before the arguments of the 
operation itself: the emtinuatiou, tlic mapping-table, and tlic original-argument- 
list. The last is a list of tlic operation name and operation arguments. ’ITic 
simplest way for tlic raround method to invoke the remaining mctliods is to do 
(lexpr-funcall-with-mapping-table 
continuation, mapping-table 
original-argument-list) 

In general, the continuation should be called with either funcall-with-mapping- 
table or lexpr-funcall-with-mapping-table, providing the continuation, the 
mapping-table, and die operation name (which you know because it is die same as 
in the defmethod), followed by whatever arguments the remaining methods are 
supposed to see. 

{defflavor foo-one-bigger-mixin {) ()) 

(defmethod (foo-one-bigger-mixin raround rset-foo) 

(cont mt ignore new-foo) 
(funcall-with-mapping-table cont mt rset-foo 

(1+ new-foo))) 

is a mixin which modifies die rset-foo operation so that the value actually used in 
it is one greater than the value specified in the message. 

rinverse-around 

rinverse-around methods work like raround methods, but they are invoked at a 
different dme and in a different order. 

With raround methods, those of earlier flavor components components are 
invoked first, starting with the instantiated flavor itself, and those of earlier 
components arc invoked within them, rinverse-around methods arc invoked in 
the opposite order; sirvanilla-flavor would come first Also, all raround methods 
and wrappers are invoked inside all the rinverse-around methods. 

For example, the rinverse-around rinit method for tvrsheet (a base flavor for all 
window flavors) is used to handle the init keywords rex pose-p and :activate-p, 
which cannot be handled correctly until the window is entirely set up. They are 
handled in this method because it is guaranteed to be the first method invoked by 
the rinit operation on any flavor of window (because no component of tvrsheet 
defines an rinverse-around method for this operation). All the rest of the work 
of making a new window valid takes place in this method’s continuation: when 
the continuation returns, the window must be as valid as it will ever be, and it is 
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ready to be exposed or activated, 
wrapper Used internally by defwrapper. 

Note that if one flavor defines both a wrapper and an :around metitod for die 
same operation, the :around method is executed inside the wrapper. 

combined Used internally for automatically-generated mubiued mcdiods. 

The most common form of combination is :daemon. One thing may not be clear: when do 
you use a :before daemon and when do you use an :after daemon? In some cases die primary 
method perfonns a clearly-defined action and the choice is obvious: :before :launch-rocket puts 
in die fuel, and :after :launch-rocket turns on the radar tracking. 

In other cases the choice can be less obvious. Consider the ;init message, which is sent to a 
newly-created object, lo decide what kind of daemon to use, we observe the order in which 

daemon methods are called. First the :before daemon of die instantiated flavor is called, then 

:before daernons of successively more basic flavors arc called, and finally die :before daemon (if 
any) of the base flavor is called. Ibcn the primary mcdiod is called. After that, die :after 
daemon for the base flavor is called, followed by the :after daemons at successively less basic 
flavors. 

Now, if there is no interaction among all these methods, if their actions are completely 

independent, then it doesn’t matter whether you use a :before daemon or an :after daemon, 

'fhere is a difference if there is some interaction. Tlie interaction we arc talking about is usually 
done through instance variables; in general, instance variables are how the methods of different 
component flavors communicate with each other. In the case of the :init operation, the init-plist 
can be used as well. 'I’he important thing to remember is that no mcdiod knows beforehand 

which other flavors have been mixed in to form this flavor; a method cannot make any 

assumptions about how this flavor has been combined, and in what order die various components 
are mixed. 

This means that when a :before daemon has run, it must assume that none of the methods 

for this operation have run yet. But the :after daemon knows that the :before daemon for each 

of die other flavors has run. So if one flavor wants to convey information to the other, the first 
one should “transmit” the Information in a ;before daemon, and the second one should “receive” 
it in an ;after daemon. So while the :before daemons are run, information is “transmitted”; that 
is, instance variables get set up, ITien, when the :after daemons arc run, they can look at the 
instance variables and act on their values. 

In the case of the :init method, the :before daemons typically set up instance variables of the 
object based on the init-plist. while the '.after daemons actually do things, relying on the fact that 
all of the instance variables have been initialized by the dme they are called. 

The problems become most difficult when you are creating a network of instances of various 
flavors that are supposed to point to each other. For example, suppose you have flavors for 
“buffers” and “streams”, and each buffer should be accompanied by a stream. If you create the 
stream in the :before ;inlt method for buffers, you can inform the stream of its corresponding 
buffer with an init keyword, but the stream may try sending messages back to the buffer, which 
is not yet ready to be used. If you create the stream in the :after :init method for buffers, there 
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will be lU) problem with stream creation, but some other :after :init methods of other mixins may 
have run and made ilie assumption that llierc is to be no stream. I'hc only way U) guarantee 
success is to create the stream in a :before method and inform it of its ass<x:iated buffer by 
sending it a message frtwi the buffer's :after :init mctliod. This scheme—creating asscKiatcd 
objects in :before methods but linking tltem up in rafter methods—often avoids problems, 
because all tltc various a.ssoeiated objects used by various mixins at least exist when it is time to 
make other objects point lo tlicm. 

Since flavors arc not hierarchically organized, flic notion of levels of abstraction is not rigidly 
applicable. However, it remains a useful way of tliinking about systems. 

21.12 ImpIcnTcntation of Flavors 

An object tliat is an instance of a flavor is implemented using the data type dtp-instance. 
'I'hc representation is a structure whose first word, tagged with dtp-instance-header, points to a 
structure (known to flic miercKode as an “instance descriptor") containing flic internal data for the 
flavor. I'hc remaining words of the structure are value cells containing flic values of flic instance 
variables. 'I'hc instiuicc descriptor is a defstruct that appears on flic sidlavor property of the 
flavor name. It contains, among other things, the name of the flavor, the size of an instance, the 
table of mefliods for handling operations, and information for accessing the instance variables. 

defflavor creates such a data structure for each flavor, and links them together according to 
the dependency relationships between flavors, 

A message is sent to an instance simply by calling it as a function, with the first argument 
being flic operation. The microcode binds self to the object and binds those instance variables 
that are supposed to be special to the value cells in the instance, 'fhen it passes on the operation 
and arguments to a ftincallablc hash table taken from the flavor-structure for this flavor. 

When tlie ftmcallable hash table is called as a function, it hashes the first argument (the 
operation) to find a function to handle the operation and an array called a mapping table. 'The 
variable sys:self-mapping-table is bound to the mapping table, which tells the microcode how 
to access the lexical instance variables, those not defined to be special. Then the function is 
called. If there is only one method to be invoked, this function is that method; otherwise it is 
an automatically-generated function called tlie combined method (see page 413), which calls the 
appropriate methods in the right order. If there are wrappers, they are incorporated into this 
combined method. 

'The mapping table is an array whose elements correspond to the instance variables which can. 
be accessed by the flavor to which the currently executing method belongs. Each clement contains 
the position in self of that instance variable, 'fhis position varies with the other instance variables 
and component flavors of the flavor of self. 

Each time the combined method calls another method, it sets up the mapping table required 
by that method—not in general the same one which the combined method itself uses. 'The 
mapping tables for the called methods are extracted from the array leader of the mapping table 
used by the combined method, which is kept in a local variable of the combined method’s stack 
frame while sys:self-mapping-table is set to the mapping tables for the component methods. 
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Variable 


Holds die current mapping Uible, which tells the running flavor mcUiod where in self to 
find each instiuice variable. 

Ordered instance variables are referred to directly without going dirough the mapping Uible; 
riiis is a little faster, and reduces die amount of space needed for mapping tables. It is also the 
reason why compiled code contains die positions of die ordered insuince variables and must be 
recompiled when diey change. 


21.12.1 Order of Definition 

’ There is a certain amount of freedom to the order in which you do defflavor’s. defmethod s, 
and defwrapper's. This freedom is designed to make it easy to load programs containing complex 
flavor structures without having to do things in a certain order. It is considered important that 
not all the methods for a flavor need be defined in the same file. 'Thus die partitioning of a 
program into files can be along modular lines. 

ITie rules for the order of definition are as follows. 

Before a method can be defined (with defmethod or defwrapper) its flavor must have been 
defined (with defflavor). ITiis makes sense because the system has to have a place to remember 
the method, and because it has to know the instance-variables of the flavor if the method is to be 
compiled. 

When a flavor is defined (with defflavor) it is not necessary that all of its component flavors 
be defined already. ITiis is to allow defflavor’s to be spread between files according to the 
modularity of a program, and to provide for mutually-dependent flavors. Methods can be defined 
for a flavor some of whose component flavors are not yet defined: however, in certain cases 
compiling those methods may produce a warning that an insuince variable was declared special 
(because the system did not realize it was an instance variable). If this happens, you should fix 
the problem and recompile. 

The methods automatically generated by the :gettable-instance-variables and :settable- 
instance-variables defflavor options (see page 424) are generated at the time the defflavor is 
done. 

The first time a flavor is instantiated, or when compile-flavor-methods is done, the system 
looks through all of the component flavors and gathers various information. At this point an error 
is signaled if not all of the components have been defflavor’ed. This is also the time at which 
certain other errors are detected, for instance lack of a required instance-variable (see the 
Tequired-instance-variables defflavor option, page 425). The combined methods (see page 413) 
are generated at this time also, unless they already exist 

After a flavor has been instantiated, it is possible to make changes to it Such changes affect 
all existing instances if possible. ITiis is described more fully immediately below. 


PS:<L.MAN>FLAVOR.TKXT.134 


8-JUN-84 



I isp Machine Manual 


44.V 


Uscrul l-ldilor Commands 


21,12.2 Changing a Flavor 

You can change anything about a flavor at any time. You can change tlic flavors general 

attributes by doing another defflavor with tlic same name. You can add or modify mctliods by 

doing defmethod’s. If you do a defmethod with the s;imc flavor-name, operation (and 
suboperation if any), and (optional) method-type as an existing method, that method is replaced 
by tlie new definition. You can remove a metliod with undefmethod (see page 419). 

■fhese changes always propagate to all flavors that depend upon die changed flavor. Normally 
the system propagates the changes to all existing instances of the changed flavor and its dependent 
flavors. However, this is not possible when Uie flavor has been changed so drastically that Uie old 
instances would not work properly with the new flavor. Ihis happens if you change die number 
of instance variables, which changes die size of an instance. It also happens if you change die 
order of the insumce variables (and hence the storage layout of an insutnee), or if you change the 
component flavors (which can change several subtle aspects of an instance). Hie system does not 

keep a list of all the instances of each flavor, so it cannot find die insuuices and modify them to 

conform to die new flavor definition. Instead it gives you a warning message, on the *error- 
outpuf stream, to the elfect diat die flavor was changed incompatibly and the old instances will 
not get the new version. Yhe system leaves the old flavor data-structurc inuict (the old instances 
continue to point at it) and makes a new one to contain the new version of die flavor. If a less 
drastic change is made, the system modifies the original flavor data-structurc, thus affecting the 
old instances that point at it. However, if you redefine mcdiods in such a way that they only 
work for the new version of the flavor, then trying to use those methods with the old instances 
won’t work. 


21.13 Useful Editor Commands 

This section briefly documents some editor commands that are useful in conjunction with 
flavors. 

Meta-. .. „ a ■ u 

The Meta-. (Edit Definition) command can find the definition of a flavor m the same 

way that it can find the definition of a function. 

Edit Definition can find the definition of a method if you give it a suitable function spec 
starting with method, such as (method tv:sheet :expose). The keyword method may 
be omitted if the definition is in the editor already. Completion is available on the flavor 
name and operation name, as usual only for definitions loaded into the editor. 

Meta-X Describe Flavor 

Asks for a flavor name in the mini-buffer and describes its characteristics. When typing 
the flavor name you have completion over the names of all defined flavors (thus this 
command can be used to aid in guessing the name of a flavor). The display produced is 
mouse sensitive where there are names of flavors and of methods; as usual the right hand 
mouse button gives you a menu of editor commands to apply to the name and the left- 
hand mouse button docs one of them, typically positioning the editor to the source code 
for that name. 

Meta-X List Methods 
Meta-X Edit Methods 
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Asks you for an operation in the mini-bufler and lists all tlic flavors tliat have a method 
for that operation. You may type in the operation name, point to it with Utc mouse, or 
let it defiuilt to the operation of the message being sent by tlie I.isp form tlie cursor is 
on. List Methods produces a mouse-sensitive display allowing you to edit selected 
methods or just to see which flavors have methods, while Edit Methods skips the display 
and pr(K'eeds directly to editing the metliods. 

As usual with tliis type of command, the editor command Control-Shift-P advances the 
editor cursor to die next mcthtid in tlte list reading in its source file if necessary. Typing 
Control-Shift-P, while the display is on die screen, edits the first method. 

In addiuon, you can find a copy of the list in the editor buffer ‘Possibilities*. While in 
diat buffer, the command Control-/ visits die definition of the mediod described on the 
line the cursor is pointing at. 

These techniques of moving through the objects listed apply to all the following 
commands as well. 

Meta-X List Combined Methods 
Meta-X Edit Combined Methods 

Asks you for an operation name and a flavor in two mini-buffers and lists all the methods 
that would be called to handle that operation for an instance of that flavor. 

List Combined Methods can be very useful for telling what a flavor will do in response 
to a message. It shows you the primary method, the daemons, and the wrappers and lets 
you see the code for all of them; type Control-Shift-P to get to successive ones. 

Meta-X List Flavor Components 
Meta-X Edit Flavor Components 

Asks you for a flavor and lists or begins visiting all the flavors it depends on. 

Meta-X List Flavor Dependents 
Meta-X Edit Flavor Dependents 

Asks you for a flavor and lists or begins visiting all the flavors that depend on it 

Meta-X List Flavor Direct Dependents 
Meta-X Edit Flavor Direct Dependents 

Asks you for a flavor and lists or begins visiting all the flavors that depend direetly on it 

Meta-X List Flavor Methods 
Meta-X Edit Flavor Methods 

Asks you for a flavor and lists or begins visiting all the methods defined for that flavor. 
(ITtis does not include methods inherited from its component flavors.) 
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21.14 Property List Operations 

It is often useful to associate a property list with an abstract object, for Ute same reasons tliat 
it is useful to have a pniperty list associated with a symbol. This section describes a mixin flavor 
that can be used as a component of any new flavor in order to provide tliat new flavor with a 
property list. For mtire details and examples, see the general discussion of property lists (section 
5.10, page 11.1). The usual property list functions (get, putprop, etc.) all work on instances by 
sending tlic instance tlie corresponding message. 

s1; property-11st-ra1x1n Flavor 

This mixin flavor provides the basic operations on property lists. 

:get property-name &optional default o/(si;property-list-mixin 

Looks up the object's property-name property. If it finds such a property, it returns the 
value; otherwise it returns default. 

tgetl property-name-list Opera/Zon o/(Si:property-list-mixin 

Like the ;get operation, except that the argument is a list of property names, llic :getl 
operation searches down the property list until it finds a property whose propeny name is 
one of the elements of property-name-list. It returns the portion of the property list 
begining with tlie first such property that it found. If it doesn’t find any, it returns nil. 

:putprop value property-name » Opera//on o/;si;property-list-mlxin 

Gives the object an property name property of value. 

(send object :set :get propertyname value) 
also has this effect. 

tremprop propertyname Operan'o/j o«si:property-list“mixin 

Removes the object’s propertyname property, by splicing it out of the property list It 
returns one of the cells spliced out, whose car is the former value of the property that 
was just removed. If there was no such property to begin with, the value is nil. 

;g 0 t-locat 1 on-or-n 11 propertyname Operano«c>nsi:property-list-mixin 

:got-location propertyname Op<?ra//o/io«si:property-list-mixin 

Both return a locative pointer to the cell in which this object’s propertyname property is 
stored. If there is no such property, :get-location-or-nil returns nil, but :get-location 
adds a cell to the property list and initialized to nil, and a pointer to that cell is returned. 

:push-property value propertyname Opera//ono/ 7 Si:property-list-mixin 

The propertyname property of the object should be a list (note that nil is a list and an 
absent property is nil). This operation sets the propertyname property of the object to a 
list whose car is value and whose edr is the former propertyname property of the list 
This is analogous to doing 

(push value (get object propertyname)) 

See the push special form (page 88). 
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: property-11 St w/si:property-list-mixin 

Returns the list of alternating property names and values Uiat implements Uie property list. 

•.property-list-location Oprra//o«o«si:property-list-mlxin 

Returns a IcKative pointer to tire cell in the instance which holds the property list data. 

:set-proporty-11st list Oprra//o/;oHSi:property-list-mixin 

Sets the list of alternating property names and values that implements the property list to 
list. So does 

(send object :set :property-1 ist list) 

:property-11st list Init option for s\:property-\\s\-m\\m 

'Phis initializes tlic list of alternating property names and values that implements the 
property list to list. 


21.15 Printing Flavor Instances Readably 

A flavor instance can print out so that it can be read back in, as long as you give it a :print- 
self method that produces a suitable printed representation, and provide a way to parse it. The 
convention for doing this is to print as 
ffeflavor-name addilional-dateo 

and make sure that the flavor defines or inherits a :read-instance method that can parse the 
additional-data and return an instance (see page 527). A convenient way of doing this is to use 
si ;pri nt - readably-mixin. 

si :pr1nt-readably-ni1x1n F/nvor 

Provides for flavor instances to print out using the # c syntax, and also for reading things 
that were printed in that way. 

; reconstruction- Init-pl 1 st Operation on si:print-readably-mixln 

When you use si:print-readably-mixin, you must define the operation :reconstruction- 
init-plist. ITiis should return an alternating list of init options and values that could be 
passed to make-instance to create an instance “like” this one. Sufficient similarity is 
defined by the practical purposes of the flavor’s implementor. 

21.16 Copying Instances 

Many people have asked “How do I copy an instance?” and have expressed surprise when 
told that the flavor system docs not include any built-in way to copy instances. Why isn’t there 
just a function copy-instance that creates a new instance of the same flavor with all its instance 
variables having the same values as in the original instance? This would work for the simplest um 
of flavors, but it isn’t good enough for most advanced uses of flavors. A number of issues are 
raised by copying: 

'* Do you or do you not send an :init message to the new instance? If you do, what init-plist 
options do you supply? 

* If the instance has a property list, you should copy the property list (e.g. with copylist) so 
that putprop or remprop on one of the instances does not affect the properties of the other 
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instance. 

* If the instance is a patliname, the concept of copying is not even meaningful. Pathnames are 
interned, which means that tlicre can only be one patliname object with any given set of 
instance-variable values. 

* If the instance is a stream connected to a network, some of Uic instance variables represent 
an agent in another host elsewhere in the network. Should tlie copy talk to the s:imc agent, 
or should a new agent be constructed for it? 

* If the instance is a stream connected to a file, should copying tlic stream make a copy of the 
file or should it make another stream open to die same file? Should the choice depend on 
whether the file is open for input or for output? 

In general, you can see Uiat in order to copy an instance one must understand a lot about 
die instance. One must know what die instiincc variables mean so that die values of the instance 
variables can be copied if neecssary. One must understand what relations to die external 
environment the instance has so diat new relations can be established for the new instance. One • 
must even understand what the general concept 'copy' means in the context of this particular 
instance, and whether it means anydiing at all. . 

Copying is a generic operation, whose implementation for a particular instance depends on 
detailed knowledge relating to that instance. Modularity dictates that this knowledge be contained 
in the instance’s flavor, not in a “general copying function”. Thus the way to copy an instance is 
to send it a message, as in (send object :copy). It is up to you to implement the operation in a 
suitable fashion, such as 

(defflavor foo (a b c) () 

(:inittable-instance-variables a b)) 

(defraethod (foo :copy) () 

(make-instance ’foo :a a :b b)) 

The flavor system chooses not to provide any default method for copying an instance, and 
does not even suggest a standard name for the copying message, because copying involves so 
many semantic issues. 

If a flavor supports the :reconstruction-init-plist operation, a suitable copy can be made by 
invoking this operation and passing the result to make-instance along with the flavor name. This 
is because the definition of what the :reconstruction-init-plist operation should do requires it to 
address all the problems listed above. Implementing this operation is up to you, and so is 
making sure that the flavor implements sufficient init keywords to transmit any information that is 
to be copied. See page 446. 
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22. The I/O System 

Zetalisp provides a powerful and flexible system for performing input and output to peripheral 
devices Device independent I/O is generalized in the concept of m I/O stream. A stream is a 
source or sink for data in the form of characters or integers: sources are called /«/)«/ streams and 
sinks are called output streams. A stream may be capable of use in eitlicr direction, in which 
case it is a bidirectional stream. In a few unusual cases, it is useful to have a ‘stream which 
supports neither input nor output: for example, opening a file with direction :probe returns one 
(page 583) Streams on which characters are transferred are called character streams, and are iised 
more often than binary streams, which usually transfer integers of type (unsigned-byte //) for 
some n. 

Streams automatically provide a modular separation between the program which hiiplcments 
tlic stream and tlie program which uses it, because streams obey a standard proUKol. ITic stream 
protocol is a special case is based on the general message passing protocol: a stream operation is 
invoked by calling tlie stream as a function, with a first argument that is a keyword and idenufies 
the 1/0 operation desired (such as, :tyi to read a character) and additional arguments as that 
operation calls for them. ITie stream protocol consists of a particular set of operation names and 
calling conventions for them. It is documented in section 22.3, page 459. 

Many programs do not invoke the stream operations directly; instead, they call standard I/O 
functions which then invoke stream operations. ITiis is done for two reasons: the functions may 
provide useful services, and they may be transportable to Common Lisp or Madisp. Programs 
that use stream operations dirccUy are not transportable outside Zetalisp. 'fhe I/O functions are 
documented in the first sections of this chapter. 

The generality of the Zetalisp I/O stream comes from the fact that I/O operations on it can 
invoke arbitrary Lisp code. For example, it would be very simple to implement a ’’morse c^e 
stream that accepted character output and used beep with appropriate pauses to display it. How 
to implement a stream is documented in section 22.3.12, page 474, and the following sections. 

The most commonly used streams are windows, which read input from the keyboard and 
dispose of output by drawing on the screen, file streams, editor buffer streams which get input 
from the text in a buffer and insert output into the buffer, and string streams which do hkewise 
with the contents of a string. 

Another unusual aspect of Lisp 1/0 is the ability to input and output general Lisp objects, 
represented as text. These are done using the read and related functions and using print and 
related functions. ITiey arc documented in chapter 23. 
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22.1 Inpul Functions 

I'hc input functions read characters, lines, or bytes from an input stream. I'his argument is 
called siream. If omitted or nil, the current value of ‘standard-input*. This is tire “default 
input stream”, which in simple use reads from the terminal keyboard. If tlie argument is t, the 
current value of *terminai-io* is used: tliis is conventionally supposed to access “the user's 
terminal” and nearly always reads from the keyboard in prcKesses belonging to windows. 

If the stream is an interactive one, such as the terminal, the input is echoed, and functions 
which read more than a single character allow editing as well, peek-char echoes all of lire 
characters that were skipped over if read-char would have echoed them; the character not 
removed from the stream is not echoed either. 

When an input stream has no more data to return, it reports end of file. Hach stream input 
operation has a convention for how to do this. I'he input functions accept an argument eof-oplion 
or two arguments eof-error and eof-value to tell tliem what to do if end of file is encountered 
instead of any input The fiinctions that take two eof- arguments are the Common Lisp ones. 
Heir tliem, end of file is an error if eof-error is non-nil or if it is unsupplied. If eof-error is nil, 
tlien the function returns eof-value at end of file. 

The functions which have one argument called eof-oplion are from Maclisp. End of file causes 
an error if tlic argument is not supplied. Otherwise, end of file causes tlie function to return the 
argument’s value. Note that an eof-oplion of nil means to return nil if the end of the file is 
reached; it is noi equivalent to supplying no eof-oplion. 

systend-of-fHe (error) Condilion 

All errors signaled to report end of file possess this condition name. 

The :stream operation on the condition instance returns the stream on which end of file 
was reached. 

22.1.1 String Input Functions 

read-line &optional siream (eof-errorpt) eof-value ignore options 

Reads a line of text, terminated by a Return. It returns the line as a character string, 
wiihoui the Return character that ended the line. The argument ignore must be accepted 
for the sake of the Common Lisp specifications but it is not used. 

Tliis function is usually used to get a line of input from the user. If rubout processing is 
happening, then options is passed as the list of options to the rubout handler (see section 
22.5, page 500). 

There is a second value, t if the line was terminated by end of file. 
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readline &optional s/mw; cof-opHon options 

Like read-line but uses tlie Maclisp convention for specifying what to do about end of 
file. Ibis function can take its first two arguments in tlic other order, for Maclisp 
compatibility only: see the note in section 22.1.3, page 451. 

read! Ine-trim &optional stream eof-option options 

This is like readline except that leading and trailing spaces and tabs are discarded from 
the value before it is returned. 

readl Ine-or-nH &optional stream eof-option options 

Like readline-trim except that nil is returned if tlic line is empty or all blank. 

read-delImited-strlng SLopikmA delimiter stream cof mbout-handlet^options buffersize 

Reads input from stream until a delimiter character is reached, tlicn returns as a string all 
tlic input up to but not including tlie delimiter, delimiter is citlicr a character or a list of 
characters which all serve as delimiters. It defaults to the character End. stream defaults 
to the value of ’standard-input*. 

If eof is non-nil. then end of file on attempting to read the first character is an error. 
Otherwise it just causes an empty string to be returned. End of file once at least one 
character has been read is never an error but it does cause tlie function to return all the 
input so far. 

• 

Input is done using rubout handling and echoing if stream supports the :rubout-handier 
operation. In this case, rubout-handleroptions are passed as the options argument to that 
operation. 

buffer-size specifies the size of string buffer to allocate initially. 

The second value returned is t if input ended due to end of file. 

The third value is the delimiter character which terminated input, or nil if input 
terminated due to end of file. This character is currently represented as a fixnum, but 
perhaps someday will be a character object instead. 


22.1.2 Character-Level Input Functions 

read-char &optional stream (eoferrorpt) eofvalue 

Reads a character from stream and returns it as a character object. End of file is an error 
if eoferrorp is non-nil; otherwise, it causes read-char to return eofvalue. This uses the 
:tyi stream operation. 

read-byte stream &optional {eoferrorpt) eofvalue 

Like read-char but returns an integer rather than a character object. In strict Common 
Lisp, only read-char can be used on character streams and only read-byte can be used 
on binary streams. 
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read-char-no-hang &optionaI sircam (cof-crwrpX) coj'-value 

Similar but returns nil immediately when no input is available on an interactive stream. 
Uses the :tyi-no-hang stream operation (page 466). 

unraad-char char &optional stream 

Puts char back \n{o stream so that it will be rctid again as tlie next input character, char 
must be die same character tliat was read from stream most recently. It may not work to 
unread two characters in a row before reading again. Uses tlie :untyi stream operation 
(page 461). 

peek-char peek-type &optional stream (eoferrorpt) eoj-value 

If peek-type is nil. tliis is like read-char except leaves tlic character to be read again by 
the next input operation. 

If peek-type is t, skips whitespace characters and peeks at the first nonwhitespace 
character. That character is the value, and is also left to be reread. 

If peek-type is a character, reads input until that character is seen. ITiat character is 
unread and also returned. 

listen (Stoptional stream 

t if input is now available on stream. Uses the :listen operation (page 466). 
cl ear-Input &optional stream 

Discards any input now available on stream, if it is an interactive stream. Uses the 
:clear-input stream operation (page 469). 

22.1.3 Maclisp Compatibility Input Functions 

These ftmetions accept an argument eofioption to tell them what to do if end of file is 
encountered instead of any input. End of file signals an error if the argument is not supplied. 
Otherwise, end of file causes the function to return the argument’s value. Note that an eof-option 
of nil means to return nil if the end of the file is reached; it is not equivalent to supplying no 
eof-option. 

The arguments stream and eof-option can also be given in the reverse order for compatibility 
with old Maclisp programs. TTie functions attempt to figure out which way they were called by 
seeing whether each argument is a plausible stream. Unfortunately, there is an ambiguity with 
symbols: a symbol might be a stream and it might be an eof-option. If there are two arguments, 
one being a symbol and the other being something that is a valid stream, or only one argument, 
which is a symbol, then these functions interpret the symbol as an eof-option instead of as a 
stream. To force them to interpret a symbol as a stream, give the symbol an si;io-stream-p 
property whose value is t. 
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tyi &optiotiat stream cof-option 

Reads one character from stream and returns it. Hie character is echoed if stream is 
interactive, cxeept dial Rubout is not echoed, 'llie Control, Meta, etc. shifts echo as C-, 
M-, etc. 

The :tyi stream operation » preferred over tlic tyi funetion for some purposes. Note that 
it does not echo. Sec page? 4lfl. 

(lliis function can take its arguments in tlie other order, for Maelisp compatibility only; 
see the note above.) 

readch &optlonal stream eof-option 

Like tyi except that instead of returning a fixnum character, it returns a symbol whose 
print name is tlie character, I'he symbol is interned in the current package. This is just 
Maclisp's version of character object. ( This ajnetion can take its arguments in the other 
order, for Maclisp compatibility only; sec the note above.) 

'I’his function is provided only for Maclisp compatibility, since in Zetalisp never uses 
symbols to represent characters in this way. 

tylpeek &optional peek-type stream eof-option 

I’his function is provided mainly for Maclisp compatibility; the :tyipeek stream operation 

is usually clearer (see page 461). 

What tyipeek does depends on the peek-type, which defaults to nil. With a peek-type of 
nil, tyipeek returns the next character to be read from stream, without actually removing 
it from the input stream. I’he next time input is done from stream the character will still 
be there; in general, (= (tyipeek) (tyi)) is t. 

If peek-type is a fixnum less than 1000 octal, then tyipeek reads characters from stream 
until it gets one equal to peek-type. That character is not removed from the input stream. 

If peek-type is t, then tyipeek skips over input characters until the start of the printed 
representation of a Lisp object is reached. As above, the last character (tlic one that starts 
an object) is not removed from the input stream. 

The form of tyipeek supported by Maclisp in which peek-type is a fixnum not less than 
1000 octal is not supported, since the readtable formats of the Maclisp reader and the 
Zetalisp reader are quite different. 

Characters passed over by tyipeek are echoed if stream is interactive. 
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22.1.4 Interactive Input with Prompting 

prompt-and-read lypc-of-parsing fonnai-siring &rcst fonnai-args 

Kcads some sort of object from *query-io*. parsing it according to type-of-parsing, and 
prompting by calling format using fonnal-slring and fonnai-args. 

lype-of parsing is either a keyword or a list starting with a keyword and continuing with a 
list of options and values, whose meanings depend on tlie keyword used. 

Most keywords specify reading a line of input and parsing it in some way. I he line can 
be terminated with Return or End. Sometimes typing Just End has a special meaning. 

'llic keywords defined arc 
:eval-sexp 

:eval-form This keyword directs prompt-and-read to accept a l.isp expression. It is 
evaluated, and the value is returned by prompt-and-read. 

If the Lisp expression is not a constant or quoted, the user is asked to 
confirm the value it evaluated to. 

A default value can be specified with an option, as in 
(: eval-sexp : def aul t default) 

Then, if the uSer types Space, prompt-and-read returns the default as 
the first value and ;default as the second value. 

:eval-sexp-or-end 

:eval-form-or-end 

Synonymously direct prompt-and-read to accept a Lisp expression or just 
the character End. If End is typed, prompt-and-read returns nil as its 
first value and :end as its second value. Otherwise, things proceed as for 
:eval-sexp. 

A default value is allowed, as in :eval-sexp, 

:read 

:expression Synonymously direct prompt-and-read to read an object and return it, 
with no evaluation. 

:expression-or-end 

Is like :expression except that the user is also allowed to type just End. 
If he does so, prompt-and-read returns the two values nil and :end. 

:number Directs prompt-and-read to read and return a number. It insists on 
getting a number, forcing the user to rub out anything else. Additional 
features can be specified with options: 

{:number :input-radix radix ;or-nil nil-ok-flag) 
parses the number using radix radix if the number is a rational. (By 
default, the ambient radix is used). If nil-ok-flag is non-nil, then the user 
is also permitted to type just Return or End, and then nil is returned. 
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idecimal-number 

:number-or-nil 

:decimal-number-or-nil 

Abbreviations for 

(inumber :input-radix 10) 

{:number :or-nil t) 

(:number :input-radix 10 :or-nil t) 

;(jate Directs prompt-and-read to read a date and time, terminated with 

Relurn or End, and return it as a universal time (sec page 777). It allows 
several options; 

(:date :never-p nevei^ok ;past-p past-required) 

If past-required is non^nil, the date must be before the present time, or 
die user must rub out and use a dilTcrcnt date. If never-ok is non-nil, the 
user may also type “never”; then nil is returned. 

:date-or-never 

:past-date 

: past-date - or - never 

Abbreviations for 

{:date :never-p t) 

(:date *.past-p t) 

{:date :never-p t :past-p t) 

:character Directs prompt-and-read to read a single character and return a 

character object representing it. 

:string Directs prompt-and-read to read a line and return its contents as a 

string, using readline. 

:string-or-nil Directs prompt-and-read to read a line and return its contents as a 
string, using readline-trim. In addition, if the result would be empty, nil 
is returned instead of the empty string. 

:string-list Like :string-trim but regards the line as a sequence of input strings 

separated by commas. Each substring between commas is trimmed, and a 
list of the strings is returned. 

:keyword-list Like :string-list but converts each string to a keyword by interning it in 
the keyword package. The value is therefore a list of keywords. 

:font-list Like :string-list but converts each string to a font name by interning it in 
the fonts package. The symbols must already exist in that package or the 
user is required to retype the input 

:delimited-string 

Directs prompt-and-read to read a string terminated by specified 
delimiters. With 

(rdelimited-string :delimiter delimiter^Ust 

:buffer-size size) 

you can specify a list of delimiter characters and an initial size for the 
buffer. The list defaults to (#\end) and the size to 100. 
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The work is done by read-delimited-string (page 450). 'ITic delimiters 
and size are passed to that function. 

:del imited - string - or - nil 

lake idelimited-string except tliat nil is returned instead of tlic empty 
string if die first character read is a delimiter. 

:host Directs prompt-and-read to read a line and interpret die contents as a 

network host name. I’he value returned is die host, looked up using 
si:parse-host (page 576). An option is defined: 

{:host :default Jcfaull-nanic :chaos-only chaos-only) 

If the line read is empty, the host named default-name is used. If chaos- 
only is non-nil, only hosts on the Chaosnet^arc pcnniltcd input. 

:host-list Like :host but regards the line as a sequence of host names separated by 
commas. Kiich host name is looked up as in :host and a list of the 
resulting hosts is returned. 

:pathname-host 

Like -.host but uses fs:get-pathname-host to look up the host object 
from its name (page 577). Thus, you find hosts that can appear in 
pathnames rather than hosts that arc on die network. 

;pathname Directs prompt-and-read to read a line and parse it as a pathname, 
merging it with the defaults. If the line is empty, the default pathname is 
used. These options are defined: 

(: p a t h n ame : d e f a u 11 s defauUs-alist-or-pathname 
: V e r s i 0 n default-version ) 

uses defaults-alist-or-pathname as the defaults argument to fs:merge- 
pathname-defaults, and default-version as the version argument to it, 

:pathname-or-nil 

Is like :pathname, but if the user types just End it is interpreted as 
meaning “no pathname” rather than “use the default”. Then nil is 
returned. 

:pathname-list 

Like :pathname but regards the line as a sequence of filenames separated 
by commas. Each filename is parsed and defaulted and a list of the 
resulting pathnames is returned. 

:fquery Directs prompt-and-read to query the user for a fixed set of alternatives, 

using fquery. type-of-parsing should always be a list, whose car is ;fquery 
and whose edr is a list to be passed aS the list of options ((query’s first 
argument). 

Example: 

(prompt-and-read ’(:fquery 

, ,format:y-or-p-options) 

"Eat it? ") 

is equivalent to 

(y-or-n-p "Eat it? ") 
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'I’his keyword is most useful as a way to get to fquery when going 
llirough an interface defined to call prompt-and-read. 

22.2 Output Functions 

'I'hcsc functions all take an optional argument called stream, which is where to send tlie 
output. If unsupplied stream defaults to die value of ‘standard-output*. If stream is nil. the 
value of ‘standard-output* (i.e. the default) is used. If it is t, the value of ‘terminal-io* is 
used (i.e. the interactive terminal). This is all more-or-less compatible with Maclisp, except that 
instead of die variable ‘standard-output* Maclisp has several variables and complicated rules, 
f'or detailed documenuilion of streams, refer to section 22 J, page 459. 

For print and the other expression output ftinctions, sec section 23.4, page 527. 

write-char char &optional stream 
tyo char &optional stream 

Outputs char to stream (using :tyo). char may be an integer or a character object; in the 
latter case, it is converted to an integer before the :tyo. 

write-byte number &optional stream 

Outputs number to stream using ;tyo. In strict Common Lisp, output to binary streams 
can be done only with write-byte and output to character streams requires write-char. 
In fact, the two functions are identical on the Lisp Machine. 

write-string string &optional stream &key (s/ar/0) end 
Outputs siring (or the specified portion of it) to stream. 

write-line string &optional stream &key (startO) end 

Outputs string (or the specified portion) to stream, followed by a Return character. 

fresh-line &optional stream 

Outputs a Return character to stream unless either 

(1) nothing has been output to stream yet, or 

(2) the last thing output was a Return character, or 

(3) stream does not remember what previous output there has been. 

This uses the :fresh-line stream operation. The value is t if a Return is output, nil if 
nothing is output, 

force-output &optional stream 

Causes stream's buffered output, if any, to be transmitted immediately. This uses the 
:force-output stream operation. 
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finish-output &optional s/mwi 

Causes sircam\ bulterc'd output, if any, to be transmitted immediately, and waits until 
that is finished. This uses tlie :finish stream operation. 

clear-output &optional stream 

Discards any output buffered in stream. 'Ihis uses tlie :clear-output stream operation, 
terprl &optional stream 

Outputs a Return character to stream. It returns t for Maclisp compatibility. It is wise 
not to depend on the value terpri returns. 

cl1:terpr1 &optional stream 

Outputs a Return character to stream. Returns nil to meet Common Lisp specifications. 
It is wise not to depend on the value cli:terpri returns. 

ITic format function (sec page 483) is very useful for producing nicely fonnatted text. It can 
do anything any of the above functions can do, and it makes it easy to produce good looking 
messages and such, format can generate a string or output to a stream. 

stream-copy-untll-eof from-stream to-stream &optional leadet^size 

stream-copy-until-eof inputs characters from from-stream and outputs tliem to to-stream, 
until it reaches the end of file on die from-stream. For example, if x is bound to a 
stream for a file opened for input, then (stream-copy-until-eof x ’terminal-io*) prints 
the file on the console. 

If from-stream supports the :line-in operation and to-stream supports the :line-out 
operation, then stream-copy-until-eof uses those operations instead of :tyi and :tyo, for 
greater efficiency, leader-size is passed as the argument to the dine-in operation. 

beep &optional beep-type (stream *terminal-iO*) 

Ihis ftmetion is intended to attract the user’s attention by causing an audible beep, or 
flashing the screen, or something similar. If the stream supports the :beep operation, 
then this function sends it a :beep message, passing beep-type along as an argument. 
Otherwise it just causes an audible beep on the terminal. 

beep-type is a keyword which explains the significance of this beep. Users can redefine 
beep to make different noises depending on the beep type. The defined beep types are: 

zwehconverse-problem 

Used for the beep that is done when Converse is unable to send a 
message. 

zwei :con verse-message - received 

Used for the beeps done when a Converse message is received. 

zweiino-completion 

Used when you ask for completion in the editor and the string does not 
complete. 

tv:notify Used for the beep done when you get a nptification that cannot be 
printed on the selected window. 
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fquery Used for Uk beep done by yes-or-no-p or by fquery with the :beep 

option specified. 

supdup:terminal-bell 

Used for the beep requested by the remote host being used tlirough a 
Siipdup window. 

nil Used whenever no other beep type applies. 

’Hie :beep operation is described on page 467. 
cursorpos &rcst args 

This function exists primarily for Maclisp compatibility. Usually it is preferable to send 
the appropriate messages (see tlie Window System manual). 

cursorpos normally operates on the ‘standard-output* stream; however, if the last 
argument is a stream or t (meaning ’terminal-io*) tlien cursorpos uses that stream and 
ignores it when doing the operations described below, cursorpos only works on streams 
that are capable of these operations, such as windows. A stream is taken to be any 
argument that is not a number and not a symbol, or that is a symbol other than nil with 
a name more than one character long. 

(cursorpos) => (line . column), the current cursor position. 

(cursorpos line column) moves the cursor to that position. It returns t if it succeeds and 
nil if it doesn’t 

(cursorpos op) performs a special operation coded by op, and returns t if it succeeds 
and nil if it doesn’t, op is tested by string comparison, it is not a keyword symbol and 
may be in any package. 

f Moves one space to the right 
b Moves one space to the left 
d Moves one line down, 

u Moves one line up. 

t Homes up (moves to the top left comer). Note that t as the last argument to 
cursorpos is interpreted as a stream, so a stream must be specified if the t 
operation is used. 

z Home down (moves to the bottom left comer), 
a AdvancesTo a fresh line. See the :fresh-line stream operation, 
c Gears the window. 

e Clear from the cursor to the end of the window: 

I Clear from die cursor to the end of the line, 

k Clear the character position at the cursor. 

X b then k. 
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22.3 I/O Streams 

An I/O stream, or just stream, is a source and/or sink of characters or bytes. A set of 
operations is available with every stream; operations include things like “output a character” and 
“input a character”. The way to perfonn an operation on a stream is the same for all streams, 
although what happens inside the stream is very different depending on what kind of a stream it 
is. So all a program has to know is how to deal with streams using tlie standard, generie 
operations. A programmer creating a new kind of stream only needs to implement the 
appropriate suindard operations, 

A stream is a message-receiving object. This means that it is something that you can apply to 
arguments. 'I'he first argument is a keyword symbol which is the name of the operation you wish 
to perform. 'Hie rest of the arguments depend on what operation you are doing. Message-passing 
and generic operations arc explained in tlie flavor chapter (chapter 21, page 401). 

Some streams can only do input, some can only do output, and some can do both. Some 
operations arc only supported by some streams. Also, there are some operations that tlic stream 
may not support by itself, but which work anyway, albeit slowly, because the stream default 
handler can handle them. All streams support the operation :which-operations, which returns a 
list of the names of all of the operations that arc supported “natively” by the stream. (:which- 
operations itself is not in the list) 

All input streams support all the standard input operations, and alt output streams support all 
the standard output operations. All bidirectional streams support bodi. 

strsamp object 

According to Common Lisp, this returns t if object is a stream. In the Lisp machine, a 
stream is any object which can be called as a function with certain calling conventions. It 
is theoretically impossible to test for this. However, streamp does return t for any of the 
usual types of streams, and nil for any Common Lisp datum which is not a stream. 


22.3.1 Standard Streams 

There are several variables whose values are streams used by many functions in the Lisp 
system. These variables and tlicir uses are listed here. By convention, variables that are expected 
to hold a stream capable of input have names ending with -input, and similarly for output 
Those expected to hold a bidirectional stream have names ending with -io. The names with 
asterisks are synonyms introduced for the sake of Common Lisp. 

♦standard-Input* Variable 

standard-input Variable 

In the normal Lisp top-level loop, input is read from ‘standard-input* (that is, whatever 
stream is the value of ‘standard-input*). Many input functions, including tyi and read, 
take a stream argument that defaults to ‘standard-input*. 
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♦standard-output* Variable 

standard-output Variable 

In the normal Lisp top-level loop, output is sent to ‘standard-output* (that is, whatever 
stream is Uic value of ‘standard-output*). Many output functions, including tyo and 
print, take a stream argument tliai defaults to ‘standard-output*. 


Variable 

Variable 


•error-output* 
error-output 

The value of ‘error-output* is a stream on which noninteractive error or warning 
messiigcs should be printed. Normally tliis is the same as standard-output , but 
‘standard-output* might be bound to a file and ‘error-output* left going to die 
terminal. 


♦debug-lo* 
debug-1o 


Variable 
Variable 

ITie value of ‘debug-io* is used for all input and output by the error handler. 
Normally this is a synonym for ‘terminal-io*. The value may be nil, which is regarded 
as equivalent to a synonym for ‘terminal-io*. ITiis feature is provided because users 
often set ‘debug-io* by hand, and it is much easier to set it back to nil afterward than 
to figure out the proper synonym stream pointing to ‘terminal-io*. 

•query-to* 

^ yoriable 

query-io « . 

The value of ‘query-io* is a stream that should be used when asking quesuons of the 
user. ITic question should be output to this stream, and the answer read from it. llie 
reason for tliis is that when the normal input to a program may be coming from a file, 
questions such as “Do you really want to delete all of the files in your directory?? should 
be sent directly to the user, and the answer should come from the user, not from the 
data file, ‘query-io* is used by (query and related functions; see page 769. 

*term1nal-1o* 

terminal-io , 

The value of ‘terminal-io* is the stream that the program should use to talk to the users 

console. In an interactive program, it is the window from which the program is being 
run; I/O on this stream reads from the keyboard and displays on the screen. However, 
in a background process that has no window, ‘terminal-io* defaults to a stream that 
does not ever expect to be used. If it is used, perhaps by an error printout, it turns into 
a background window and requests the user’s attention. 


•trace-output* 
trace-output 

The value of ‘trace-output* is the stream on which the trace function prints its output. 


Variable 

Variable 


‘standard-input*, ‘standard-output*, ‘error-output*, *debug-io‘, ‘trace-output*, and 
‘query-io* arc initially bound to synonym streams that pass all operations on to the stream that 
is the value of ‘terminal-io*. Thus any operations performed on those streams go to the 
keyboard and screen. 
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Most user programs should not change tlic value of ‘terminal-io*. A program which wants 
(for example) to divert output to a file should do so by binding the value ot ‘standard-output*; 
tliat way queries on ‘query-io‘, debugging on ‘debug-io‘ and error messjiges sent to ‘error- 
output* can still get to die user by going through ‘terminal-io‘, which is usually what is 
desired. 

22.3.2 Staiidartl Input Stream Operations 

:ty1 &optional eof Operation on sireams 

The stream inputs one character and returns it. For example, if the next character to be 
read in by the stream is a ‘C’, then tlie form 
(send s :tyi) 

returns tlie value of #/C (that is. 103 tKtal). Note that the :tyi operation docs not echo 
die character in any fashion; it just docs the input. I’hc tyi function (sec page 452) docs 
echoing when reading from the terminal. 

llic optional eo/argument to the ;tyi operation tells the stream what to do if it gets to 
the end of the file. If the argument is not provided or is nil, the stream returns nil at 
the end of file. Otherwise it signals a sys:end-of-file error. Note that this is not the 
same as die eof-option argument to read, tyi, and related fiinctions. 

The :tyi operation on a binary input stream returns a non-negative number, not 
necessarily to be interpreted as a character. 

For some streams (such as windows), not all the input data are numbers. Some are lists, 
called blips. Ihe :tyi operation returns only numbers. If the next available input is not a 
number, it is discarded, and so on until a number is reached (or end of file is reached). 

:any- ty1 &optional eof Operation on sireams 

Like :tyi but returns any kind of datum. Non-numbers are not discarded as they would 
be by :tyi. This distinction only makes a difference on streams which can provide input 
which is not composed of numbers; currently, only windows can do that 

itylpeek &optional eof Operation on streams 

Pecks at the next character or byte from the stream without discarding it. The next :tyi 
or dyipeek operation will get the same character. 

eof is the same as in the :tyi operation; if nil, end of file returns nil; otherwise, it 
signals a sys:end-of-file error. 

tun tyi char Operation on sireams 

Unreads the character or byte char, that is to say, puts it back into the input stream so 
that the next :tyi operation will read it again. For example, 

(send s tuntyi 120) 

(send s :tyi) ==> 120 

This operation is used by read, and any stream that supports :tyi must support tuntyi as 
well. 
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You are only allowed to :untyi one character before doing a ;tyi, and die character you 
runtyi must be the last character read from die stream. I’hat is. :unlyi can only be used 
to back up one character, not to stuff arbitrary data into die stream. You also can’t 
:untyi after you have pecked ahead with :tyipeek since diat docs one luntyi itself. Some 
streams implement :untyi by saving die character, while others implement it by backing 
up die pointer to a buffer. 

:stp1ng-in siring &optional (.v/rtr/ 0) end Operation on streams 

Reads characters from the stream and stores them into die array siring. Many streams 
can implement this far more efficiently that repeated :tyi's. start and end, if supplied, 
delimit die portion of siring to be stored into. If eof-option is non-nil dicn a sys:end-of- 
file error is signaled if end of file is reached on die stream before die string has been 
filled. If eof-option is nil, any number of cliaractcrs before end of file is acceptable, even 
no characters. 

If string has an array-leader, die fill pointer is adjusted to start plus the number of 
characters stored into siring. 

Two values arc returned: the index of the next position in string to be filled, and a flag 
that is non-nil if end of file was reached before string was filled. Most callers do not 
need to look at either of these values. 

string may be any kind of array, not necessarily a string; this is useful when reading 
from a binary input stream. 

;l1n0-1n Aoptional leader Operation on streams 

'fhe stream should input one line from the input source, and return it as a string with the 
carriage return character stripped off. Contrary to what you might assume from its name, 
this operation is not much like the readline function. 

Many streams have a string that is used as a buffer for lines. If this string itself were 
returned, there would be problems caused if the caller of the stream attempted to save 
the string away somewhere, because the contents of the string would change when the 
next line was read in. In order to solve this problem, the string must be copied. On the 
other hand, some streams don’t reuse the string, and it would be wasteful to copy it on 
every :line-in operation. ITiis problem is solved by using the leader argument to :line-in. 
If leader is nil (tlic default), the stream does not bother to copy the string and the caller 
should not rely on the contents of that string after the next operation on the stream. If 
leader is t, the stream does make a copy. If leader is a fixnum then the stream makes a 
copy with an array leader leader elements long. (This is used by the editor, which 
represents lines of buffers as strings with additional information in their array-leaders, to 
eliminate an extra copy operation.) 

If the stream reaches end of file while reading in characters, it returns the characters it 
has read in as a string and returns a second value of t. Tlie caller of the stream should 
therefore arrange to receive the second value, and check it to see whether the string 
returned was a whole line or just the trailing characters after the last carriage return in the 
input source. 
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Hiis operation should be implemented by all input streams whose daui arc characters. 

rstrlng-line-ln eof-oplion siring &optional (starl 0) end Operation on sireams 

Reads characters, storing them in siring, until siring is full or a Return character is read. 
If input stops due to a Return, the Return itself is not ptit in tlic buffer. 

1'hus, this operation is nearly die same as :string-in, except tliat :string-in always keeps 
going until the buffer is full or until end of file. 

start and end, if supplied, delimit the portion of siring to be stored into. If eof-oplion is 
non-nil tlten a sysiend-of-file error is signaled if end of file is reached on tlie stream 
before the string has been filled. If eof-oplion is nil, any number of characters before end 
of file is acceptable, even no characters. 

If siring has an array-leader, the fill pointer is adjusted to starl plus tlie number of 
characters stored into siring. 

string may be any kind of array, not necessarily a string: tliis is useful when reading 
from a binary input stream. 

Three values are returned: 

(1) 'fhe index in siring at which input stopped. This is the first index not stored in. 

(2) t if input stopped due to end of file, 

(3) t if the line is incomplete; that is, if a Return character did not terminate it. 

: read-unt11 -eof Operation on streams 

Discards all data from the stream until it is at end of file, or does anything else with the 
same result 

:close Aoptional ignore Operation on streams 

Releases resources associated with the stream, when it is not going to be used any more. 
On some kinds of streams, this may do nothing. On Chaosnet streams, it closes the 
Chaosnet connection, and on file streams, it closes the input file on the file server. 

The argument is accepted for compatibility with :close on output streams. 


22.3.3 Standard Output Stream Operations 

:tyo char Operation on streams 

The stream outputs the character char. For example, if s is bound to a stream, then the 
form 

(send s :tyo #/B) 

outputs a B to the stream. For binary output streams, the argument is a non-negative 
number rather than specifically a character. 
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: fresh-line Opcniiion on sireams 

I'clls the stream that It should position itself at tite beginning of a new line. If tlte stream 
is already at the beginning of a fresh line it should do nothing; otherwise it should 
output a carriage return. If the stream cannot tell whether it is at tlte beginning of a line, 
it should always output a carriage return. 

: string-out {siring 0) &optional stor/ end Operaiion on streams ^ 

Outputs the characters of string successively to stream. 'I'his operation is provided for two 
reasons; first, it saves tlte writing of a loop which is used very often, and sa'ond, many 
streams can perfonn this operation much more efficiently titan tlte equivalent sequence of 
:tyo operations. 

If start and end arc not supplied, Utc whole string is output. Otherwise a substring is 
output; start is the index of the first character to be output (defaulting to 0). and end is 
one greater than tlte index of the last character to be output (defaulting to the length of 
the string). Callers need not pass Utese arguments, but all streams tliat handle :string-out 
must check for tlicm and interpret tliem appropriately. 

: line-out siring &optional {start 0) end Operation on sireams 

Outputs the characters of siring successively to stream, then outputs a Return character. 
start and c/n/ optionally specify a substring, as with :string-out. If the stream doesn’t 
support :line-out itself, the default handler implements it by means of :tyo. 

This operation should be implemented by all output streams whose data are characters. 

: c 1 ose &optionaV mode Operaiion on streams 

Closes the stream to make the output final if this is necessary. The stream becomes closed 
and no further output operations should be performed on it. However, it is all right to 
xiose a closed stream. On many file server hosts, a file being written is not accessible to 
be read until the output stream is closed. 

This operation does nothing on streams for which it is not meaningful. 

The mode argument is noimally not supplied. If it is labort, we arc abnormally exiting 
from the use of this stream. If the stream is outputting to a file, and has not been closed 
already, tlie stream’s newly-created file is deleted; it will be as if it was never opened in 
the first place. Any previously existing file with the same name remains undisturbed. 

. eof Operation on streams 

Indicates the end of data on an output stream. This is different from xiose because 
some devices allow multiple data files to be transmitted without closing, xiose implies 
:eof when the stream is an output stream and the close mode is not :abort. 

This operation docs nothing on streams for which it is not meaningful. 
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22.3.4 Asking Streams VVhal They Can Do 

All streams arc supposed to support certain operations which enable a program using the 
stream to ask which operations are available. 

:wh1ch-operations Operation on streams 

Returns a list of operations handled natively by die stream. Ceruiin operations not in the 
list may work anyway, but slowly, so it is just as well if any programs Uiat work with or 
without diem choose not to use diem. 

:which-operations itself need not be in die list. 

:operat1on-hand1ed-p operation Operation on streams 

Returns t if operation is handled natively by die stream: if operation is a member of the 
:which-operations list, or is :which-operations. 

: send- If -handles operation &rest arguments Operation on streams 

Performs the operation operation, with the specified arguments, only if the stream can 
handle it. If operation is handled, this is the same as sending an operation message 
directly, but if operation is not handled, using :send-if-handles avoids any error. 

If operation is handled, :send-if-handles returns whatever values the execution of the 
operation returns. If operation is not handled, :send-if-handles returns nil. 

: direction Operation on streams 

Returns :input, :output, or rbidirectional for a bidirectional stream. 

There are a few kinds of Streams, which cannot do cither input or output, for which the 
:direction operation returns nil. For example, open with the :direction keyword specified 
as nil returns a stream-like object which cannot do input or output but can handle certain 
file inquiry operations such as :truename and :creation-date. 

: characters Operation on streams 

Returns t if the data input or output on the stream represent characters, or nil if they are 
just numbers (as for a sbeam reading a non-text file). 

:e1einent-type Operation on streams 

Returns a type specified describing in principle the data input or output on the stream. 
Refer to the function stream-element-type, below, which works using this operation. 
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These fiinetions (or inquiring about streams arc defined by Common Lisp. 

Input-stream-p sireani 

t if s/rram handles input operations (at least, if it handles :tyi). 
output-stream-p stream 

t if stream handles output operations (at least, if it handles :tyo). 

Stream-element- type stream 

Returns a type specifier which describes, conceptually, the kind of data input from or 
output to stream. The value is always a subtype of integer (for a binary stream) or a 
subtype of character (for a character stream). If it is a subtype of integer, a Common 
I.isp program should use read-byte (page 450) or write-byte (page 456) for I/O. If it is 
a subtype of character, read-char (page 450) or write-char (page 456) should be used. 

I'hc value returned is not intended to be rigidly accurate. It describes die typical or 
characteristic sort of data transferred by the stream, but the stream may on occasion deal 
with data that do not fit the type; also, not all objects of the type may be possible as 
input or even make sense as output. For example, windows describe tlieir element type 
as character even tliough tliey may offer blips, which arc lists, as input on occasion. In 
addition, streams which say they provide characters really return integers if the :tyi 
operation is used ratlicr than tlic standard Common Lisp function read-Char. 


22.3.5 Operations for Interactive Streams 

I'he operations :listen, :tyi-no-hang, :rubout-handler and :beep arc intended for interactive 
streams, which communicate with the user, ilisten and :tyi-no-hang arc supported in a trivial 
fashion by other streams, for compatibility. 

: listen Operation on streams 

On an interactive device, the :listen operation returns non-nil if there are any input 
characters immediately available, or nil if tlicre is no immediately available input On a 
non-interactivc device, the operation always returns non-nil except at end of file. 

I’hc main purpose of listen is to test whether the user has hit a key, perhaps trying to 
stop a program in progress. 

:tyi-no-hang &optional eof Operation on streams 

Just like :tyi except that it returns nil rather than waiting if it would be necessary to wait 
in order to get the character. This lets die caller check efficiently for input being available 
and get the input if there is any. 

:tyi-no-hang is different from :listen because it reads a character. 

Streams for which the question of whether input is available is not meaningful treat this 
operation just like :tyi. So do Chaosnet file streams. Although in fact reading a character 
from a file stream may involve a delay, these delays are supposed to be insignificant, so 
we pretend they do not exist. 
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:any-ty1-nD-hang &i>ptional eof Operation on streams 

l.ikc :tyi-no-hang but docs not filter and discard input which is not numbers. It is 
therefore possible to see blips in the input stream. I'hc distinctiom matters only for input 
from windows. 

: rubout-handler options function &rest args Operation on streams 

riiis is supported by interactive bidirectional streams, such as windows on the terminal, 
and is described in its own section below (see section 22.5, page 500). 

;beep &optional OK Operation on streams 

riiis is supp(»rtcd by interactive streams. It attracts tlie attention of the user by making an 
audible beep and/or flashing the screen, beep-type is a keyword selecting among several 
diftcrent beeping noises; see beep (page 457) for a list of them. 

22.3.6 Cursor Positioning Stream Operations 

:read-cursoppos &optional (units :pixel) Operation on streams 

'I'his operation is supported by all windows and some otlicr streams. 

It returns two values, the current x and y coordinates of the cursor. It takes one optional 
argument, which is a symbol indicating in what units jf and y should be; the symbols 
:pixel and icharacter are understood. :pixel means that the coordinates are measured in 
display pixels (bits), while tcharacter means that the coordinates arc measured in 
characters horizontally and lines vertically. 

This operation and :increment-cursorpos are used by the format ~T request (see page 
487), which is why ~T doesn’t work on all streams. Any stream that supports this 
operation should support :increment-cursorpos as well. 

Some streams return a meaningful value for the horizontal position but always return zero 
for the vertical position. This is sufficient for ~T to work. 

: Increment-cursorpos Operation on streams 

x-increment y-increment &optional (units :pixel) 

Moves the stream’s cursor left or down according to the specified increments, as if by 
outputting an appropriate number of space or return characters. Jf and y are like the 
values of :read-cursorpos and units is the same as the units argument to :read- 
cursorpos. 

Any stream which supports this operation should support rread-cursorpos as well, but it 
need not support :set-cursorpos. 

Moving the cursor with rincrement-cursorpos differs from moving it to the same place 
with :set-cursorpos in that this operation is thought of as doing output and :set- 
cursorpos is not. For example, moving a window’s cursor down with :increment- 
cursorpos when it is near the bottom to begin with will wrap around, possibly doing a 
**MORE**. :set-cursorpos, by comparison, cannot move the cursor “down” if it is at 
the bottom of the window; it can move the cursor explicitly to the top of the window, 
but then no **MORE** will happen. 
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Some streams, such as those created by with-output-to-string, cannot implement 
arbitrary cursor motion, but do implement this operation. 

:set-cursorpos x y &optional {units :pixel) Operation on streams 

This operation is supported by the same streams Uiat support :read-cursorpos. It sets 
the position of tlic cursor, x and y arc like the values of :read-cursorpos and units is 
the same as the units argument to :read-cursorpos. 

: cl ear-screen Operation on streams 

Hrascs die screen area on which this stream displays. Non-window streams don’t support 
tliis operation. 

'Ihcrc arc many other special-purpose stream operations for graphics, 'fhey arc not 
documented here, but in the window-system documenUttion. No claim tliat the above operations 
arc die most useful subset should be implied. 

22.3.7 Operations for Efficient Pretty-Printing 

grindef runs much more efficiently on streams that implement the :untyo-mark and :untyG 
operations. 

:untyo-inark , Operation on streams 

This is used by the grinder (see page 528) if die output stream supports it. It takes no 
arguments. ITic stream should return some object that indicates how far output has gotten 
up to in the stream. 

:untyo mark Operation on streams 

'lliis is used by the grinder (see page 528) in conjunction with :untyo-mark. It takes one 
argument, which is something returned by the :untyo-mark operation of the stream. The 
stream should back up output to the point at which the object was returned. 

22.3.8 Random Access File Operations 

The following operations arc implemented only by streams to random-access devices, 
principally files. 

: read-pointer Operation on streams 

Returns the current position within the file, in characters (bytes in fixnum mode). For 
text files on ASCII file servers, this is the number of Lisp Machine characters, not ASCII 
characters. The numbers are different because of character-set translation. 

: set-pointer newpoinler Operation on streams 

Sets die reading position within the file to new’-pointer (bytes in fixnum mode). For text 
files on ASCII file servers, this docs not do anything reasonable unless imvpointer is 0, 
because of character-set translation. Some file systems support this operation for input 
streams only. 
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: rewind Openuion on streams 

riiis operation is obsolete. It is tiic same as :set-pointer with argument zero. 

22.3.9 BufTcred Stream Operations 

;c1ear-1nput 

Discards any buffered input the stream may have, 
is not meaningful. 

: cl ear-output Operation on streams 

Discards any buffered output the stream may have. It does nothing on streams for which 
it is not meaningful. 

: force-output Operation on streams 

'Hiis is for output streams to buffered asynchronous devices, such as the Chaosnet. 
:force-output causes any buffered output to be sent to the device. It docs not wait for it 
to complete; use rfinish for that. If a stream supports :force-output, then :tyo, :string- 
out, and :line-out may have no visible effect until a :force-output is done. 

This operation does nothing on streams for which it is not meaningful. 

tflnlsh Operation on streams 

ITiis is for output streams to buffered asynchronous devices, such as the Chaosnet. :finish 
docs a :force-output, then waits until the currently pending 1/0 operation has been 
completed, 

'Phis operation does nothing on streams for which it is not meaningful. 

The following operations are implemented only by buffered input streams. They allow 

increased efficiency by making the stream’s internal buffer available to the user. 

tread-Input-buffer &optional eof Operation on streams 

Returns three values: a buffer array, the index in that array of the next input byte, and 
the index in that array just past the last available input byte. These values are similar to 
the string, start, end arguments taken by many functions and stream operations. If the 
end of the file has been reached and no input bytes are available, this operation returns 
nil or signals an error, based on the eof argument, just like the :tyi operation. After 
reading as many bytes from the array as you care to, you must use the ladvance-input- 
buffer operation. 

: get-Input-buffer &optional eof Operation on streams 

This is an obsolete operation similar to :read-input-buffer. The only difference is that 
tlie third value is the number of significant elements in the buffer-array, rather than a 
final index. If found in programs, it should be replaced with :read-input-buffer. 


Operation on streams 
It docs nothing on streams for which it 
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:advance-1nput-buffer Aoptional iw^’-pomier Opcraikm on streams 

if ncn^pointer is non-nil, il is the index in tlic buffer array of the next byte to be read. 
If neiv-pointer is nil, the entire buffer has been used up. 

22.3.10 Obtaining Streams to Use 

Windows arc one important class of streams. Hach window can be used as a stream. Output 
is displayed on the window and input comes from the keyboard. A window is created using 
make-instance on a window flavor. Simple programs use windows implicitly through ’terminal- 
io* and the other standard stream variables. 

Also important are file streams, which arc produced by the function open (sec page 582). 
riicse read or write the contents of a file. 

Chaosnet streams are made from Chaosnet connections. Data output to the stream goes out 
over the network; data coming in over die network is available as input from the stream. File 
streams that deal with Chaosnet file servers arc very similar to Chaosnet streams, but Chaosnet 
streams can be used for many purposes other than file access. 

String streams read or write the contents of a string. They arc made by with-output-to- 
string or with-input-from-string (sec page 473), or by make-string-input-stream or make¬ 
string-output-stream, below. 

Editor buffer streams read or write the contents of an editor buffer. 

ITtc null stream may be passed to a program that asks for a stream as an argument. It 
returns immediate end of file if used for input and throws away any output. The null stream is 
Uic symbol si:null-stream. I'his is to say, you do not call that function to get a stream or use 
tlic symbol’s value as the stream; the symbol itself is tlic object that is the stream. 

The cold-load stream is able to do I/O to the keyboard and screen without using the window 
system. It is what is used by tlic error handler, if you type Terminal Call, to handle a 
background error tliat the window system cannot deal with. It is called the cold-load stream 
because it is what is used during system bootstrapping, before the window system has been 
loaded. 

sltnull-stream operation &rest arguments 

This function is the null stream. Like any stream, it supports various operations. Output 
operations arc ignored and input operations report end of file immediately, with no data. 
Usage example: 

(let {(♦standard-output* ’si:nul1-stream)) 

(function-whose-output-I-dont-want)) 

si rcold-load-stream Constant 

'I'hc one and only cold-load stream. Usage example: 

(let ((*query-io* si :cold-load-stream)) 

(yes-or-no-p "Clear all window system locks? ")) 
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wlth-open-stream {variable expression) body... Macro 

body is executed with variable bound to the value of expressknu which ought to be a 
stream. On exit, whether nonnal or by tlirowing, a :close message with argument :abort 
is sent to Uic stream. 

This is a generalization of with-open-file, which is equivalent to using with-open- 
stream with a call to open as tlic expression. 

wlth-open-stream-case {variable expression) clauses... Macro 

l ike with-open-stream as far as opening and closing the stream are concerned, but 
instead of a simple body, it has clauses like tliosc of a condition-case diat say what to 
do if expression docs or docs not get an error. Sec with-open-file-case, page 580. 

make-synonym-stream symboi-or^iocative 
make-syn-stream symbol-or-locative 

Creates and returns a synonym stream (‘syn’ for short). Any operations sent to tlds stream 
arc redirected to the stream that is the value of the argument (if it is a symbol) or the 
contents of it (if it is a locative). 

A synonym stream is actually an uninterned symbol whose flinction defnition is forwarded 
to the function cell of the argument or to the contents of tlic argument as appropriate. If 
the argument is a symbol, the synonym stream's print-name is symbol-syn-stream; 
otherwise the name is just syn-stream. Once a synonym stream is made for a symbol, it 
is recorded, and the same one is handed out again if there is another request for it. 

ITie two names for this function are synonyms too. 

make-concatenated-stream &rcst streams 

Returns an input stream which will read its input from the first of streams until that 
reaches its eof, then read input from the second of streams, and so on until the last of 
streams has reached end of file. 

make-two-way-stream input-stream output-stream 

Returns a bidirectional stream which passes input operations to input-stream and passes 
output operations to output-stream. 'ITiis works by attempting to recognize all standard 
input operations; anything not recognized is passed to output-stream. 

make-echo-strearo input-stream output-stream 

Like make-two-way-stream except that each input character read via input-stream is 
output to output-stream before it is returned to the caller. 

make-broadcast-stream &rest streams 

Returns a stream that only works in the output direction. Any output sent to this stream 
is forwarded to all of the streams given. The :which-operations is the intersection of the 
:which-operations of all of the streams. 'I'he valuc(s) returned by a stream operation are 
the values returned by the last stream in streams. 
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zwe1:Interval-Stream inicrval-oi'-from-bp (feoplional lo-bp in-order-p liack-Jbnis 

Returns a bidirectional stream tliat reads or writes all or part of an editor buffer. Note 
that editor buffer streams can also be obtained from open by using a padmamc whose 
host is ED, ED-BUFFER or ED-FILE (see section 24.7.6, page 575). 

The first tliree arguments specify the buffer or portion to be read or written. Hither the 
first argument is an interval (a buffer is one kind of interval), and all tJic text of tJiat 
interval is read or written, or the first two arguments are two buffer pointers delimiting 
the range to be read or written, 'flic third argument is used only in tlic latter case; if 
non-nil, it tells tlic function to assume tliat the second buffer pointer comes later in the 
buffer tlian tlic first and not to take the time to verify the assumption. 

The stream has only one pointer inside it. used for both input and output. As you do 
input, tlic pointer advances tlirough the text. When you do output, it is inserted in the 
buffer at the place where tlie pointer has reached. The pointer suirts at the beginning of 
the specified range. 

hack-fonts tells what to do about fonts. Its possible values are 

t I'he character t is recognized as special when you output to the stream; 

sequences such as e2 arc interpreted as font-changes. They do not get 
inserted into the buffer; instead, tlicy change the font in which following 
output will be inserted. On inpuL font change sequences arc included to 
indicate faithfully what was in the buffer. 

:tyo You arc expected to read and write 16-bit characters containing font 

numbers. 

nil All output is inserted in font zero and font information is discarded in the 

input you receive. This is the best mode to use if you are reading or 
otherwise parsing the contents of an editor buffer. 

sys:w1th-help-stream {stream options...) body... Macro 

Executes the body with the variable stream bound to a suitable stream for printing a large 
help message. If 'standard-output* is a window, then stream is also a window; a 
temporary window which fills the screen. Otlierwise, stream is just the same as 
'standard-output*. 

The purpose of this is to spare the user the need to read a large help printout in a small 
window, or have his data overwritten by it permanently. This is tlic mechanism used if 
you type the Control-Help key while in the rubout handler. 

options is a list of alternating keywords and values. 

:label llie value (which is evaluated) is used as the label of the temporary 

window, if one is used. 

;width ITie value, which is not evaluated, is a symbol. While body is executed, 

this symbol is bound to the width, in characters, available for the 
message. 
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:height The value is a symbol, like tlie value after ;width, and it is bound to the 

height in lines of the area available for the help message. 

isuperior The value, which is evaluated, specifies tlie original stream to use in 
deciding where to print the help message. I'he default is ‘standard- 
output*. 

22.3.11 String I/O Streams 

The functions and special forms in this section allow you to create I/O streams tliat input 
from or output to tlie contents of a string. 

make-string-lnput-stream siring &optional (siartO) end 

Returns a stream which can be used to read tlie contents of string (or the portion of it 
from index start to index end) as input. End of file (Kcurs on reading past position end 
or tlie end of string. 

make-str1ng-output-streara Aoptional string 

Returns an output stream which will accumulate all output in a string. If string is non-nil, 
output is added to it with string-nconc (page 216). Otherwise, a new string is created 
and used to hold the output. 

get-output-stream-strlng string-ouiput-stream 

Returns the string of output accumulated so far by a stream which was made by make¬ 
string-output-stream. The accumulated output is cleared out, so it will not be obtained 
again if get-output-stream-string is called another time on the same stream. 

w1th-input-frora-stPlng {var string &kcy start end index) body.., Macro 

The form 

(with-input-from-string {var string) 
body) 

evaluates the forms in body with the variable var bound to a stream which reads 
characters from the string which is the value of the form string. The value of the 
construct is the value of the last form in its body. 

If the start and end arguments are specified, they should be forms. They are evaluated at 
run time to produce the indices starting and ending the portion of string to be read. 

If the index argument is specified, it should be something self can store in. When body 
is finished, the index in the string at which reading stopped is stored there. This is the 
index of the first character not read. If the entire string was read, it is the length of the 
string. The value of index is not updated until with-input-from-string is exited, so you 
can’t use its value within the body to see how far the reading has gotten. Example: 
(with-input-from-string 

(foo "This is a test." :start (+ 2 2) rend 8 rindex bar) 
(readline)) 

returns " is " and sets bar to eight. 
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An older calling sequence which used positional ratlier than keyword arguments is still 
accepted: 

(with-input-from-string (v’rtr 5//7//i’ index end) 
body) 

1'he functions read-from-string and clirread-from-string arc convenient special cases of 
what with-input-from-string can do. Sec page 533. 

w1th-output-to-stPing (var [siring [/w/c.v]]) body... Macro 

This special fonn provides a variety of ways to send output to a string through an I/O 
stream. 

(with-output-to-string (var) 
body) 

evaluates tlic forms in body with var bound to a stream which saves the characters output 
to it in a string. I'he value of the special fonn is the string. 

(with-output-to-string (var string) 
body) 

appends its output to tlie string which is the value of the form siring. ClTiis is like the 
string-nconc function; see page 216.) The value returned is the value of tlie last form in 
the body, ratlier tlian tlie string. Multiple values arc not returned, siring must have a fill 
pointer. If siring is too small to contain all the output, adjust-array-size is used to 
make it bigger. 

(with-output-to-string (var siring index) 
body) 

is similar to tlie above except that index is a variable or setf-able reference which contains 
die index of the next character to be stored into. It must be initialized before the with- 
output-to-string and it is updated upon normal exit. The value of index is not updated 
until with-output-to-string returns, so you can’t use its value within the body to see 
how far the writing has gotten. The presence of index means that string is not required 
to have a fill-pointer; if there is one, it is updated on exit. 

Another way of doing output to a string is to use the format facility (see page 483). 

22.3.12 Implementing Streams 

There arc two ways to implement a stream: using defun or using flavors. 

Using flavors is best when you can take advantage of the predefined stream mixins, including 
those which perform buffering, or when you wish to define several similar kinds of streams that 
can inherit methods from each other. 

defun (or defselect, which is a minor variation of the technique) may have an advantage if 
you arc dividing operations into broad groups and handling them by passing them off to one or 
more other streams. In tliis case, the automatic operation decoding provided by flavors may get 
in the way. A number of streams in the system arc implemented using defun or defselect for 
historical reasons. It isn’t yet clear whether there is any reason not to convert most of them to 
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use flavors. 

If you use defun, you can use the stream default handler to impletnenl some of the standard 
operations for you in a default manner. If you use flavors, tlierc are predefined mixins to do this 
for you. 

A few streams are individual objects, one of a kind. For example, tlicrc is only one null 
stream, and no need for more, since two null streams would behave identically. lUil most streams 
arc elements of a general class. For example, tJicrc can be many file streams for diflerent files, 
even though all behave the same way. 'I’here can also be multiple streams reading from different 
points in the same file. 

If you implement a class of streams with defun, then the actual streams must be closures of 
die function you define, made with closure. 

If you use flavors to implement the sU'eams, having a class of similar streams comes naturally: 
each instance of the flavor is a stream, and flic instance variables distinguish one stream of the 
class from another. 

22.3.13 Implementing Streams with Flavors 

To define a stream using flavors, define a flavor which inconjorates the appropriate predefined 
stream flavor, and then redefine those operations which are peculiar to your own type of stream. 

Flavors for defining unbuffered streams: 

s1: stream Flavor 

This flavor provides default definitions for a few standard operations such as :direction 
and :characters. Usually you do not have to mention this explicitly; instead you use the 
higher level flavors below, which are built on this one. 

s1: Input-stream Flavor 

This flavor provides default definitions of all the mandatory input operations except :tyi 
and :untyi, in terms of those two. You can make a simple non-character input stream by 
defining a flavor incorporating this one and giving it methods for :tyi and :untyi. 

s1 :output-strearo Flavor 

ITiis flavor provides default definitions of all the mandatory output operations except :tyo, 
in terms of :tyo. All you need to do to define a simple unbuffered non-character output 
stream is to define a flavor incorporating this one and give it a method for the :tyo 
operation. 

s1:b1d1rect1ona1-stream Flavor 

This is a combination of si:input-stream and si:output-stream. It defines :direction to 
return :bidirectional. To define a simple unbuffered non-character bidirectional stream, 
build on this flavor and define :tyi, ;untyi and :tyo. 
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Ihc unbulfcrcd streams implement operations such as ;string-out and :string-in by repeated 
use of :tyo or :tyi. 

For greater efficiency, if the stream’s data is available in bkKks, it is better to define a 
buffered stream. You sutri with tlie predefined buffered stream flavors, which define :tyi or :tyo 
themselves and manage the buffers for you. You must provide other operations Uiat the system 
uses to obtain the next input buffer or to write or discard an output buffer. 

Flavors for defining buffered streams: 

s 1 :buffeped- 1 nput-str®ara 'T'Z 

This flavor is llic basis for a non-character buffered input stream. It defines :tyi as well as 

all the other standard input operations, but you must define the two operations ;next- 
input-buffer and :discard-inpat-buffer. which the buffer management routines use. 

rnext-input-buffer o« si:bufte^^^ ■ 

In a buffered input stream, this operation is used as a subroutine of the sfcmdard input 
operations, such as :tyi, to get the next bufferful of input data. It should return three 
values: an array containing the data, a starting index in the array, and an ending index. 
For example, in a Chaosnet stream, this operation would get the next packet of input 
data and return pointers delimiting the actual data in the packet. 

:d 1 scard- 1 nput-buffep buffer-array Opera/io/ioHSi;buffered-input-stream 

In a buffered input stream, this operation is used as a subroutine of the standard input 
operations such as ;tyi. It says that the buffer management routines have used or thrown 
away all the input in a buffer, and the buffer is no longer needed. 

In a Chaosnet stream, this operation would return the packet buffer to the pool of free 
packets, 

FIqvot 

si ;buffered-output-streara „ j 

This flavor is the basis for a non-character buffered output stream. It defines .tyo as well 

as all the other standard output operations, but you must define the operations :new- 
output-buffer. :send-output-buffer and :discard-output-buffer, which the buffer 
management routines use. 

• new-output-buffer Operation on sitbuffered-output-stream 

In a buffered output stream, this operation is used as a subroutine of the standard output 
operations, such as :tyo, to get an empty buffer for storing more output data. How the 
buffer is obtained depends on the kind of stream, but in any case this ^cration shouW 
return an array (the buffer), a starting index, and an ending index, fhe two indices 
delimit the part of the array that is to be used as a buffer. 

For example, a Chaosnet stream would get a packet from the free pool and return indices 
delimiting the part of the packet array which can hold data bytes. 
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rsend-output-buffer Operation onsi.bufiered-outpot-stream 

buffet"array ending-index 

In a biiflcred output stream, tliis operation is used as a subroutine of die suindard output 
operations, such as :tyo, to send die data in a buffer diat has been completely or partially 
filled. 

ending-index is the first index in the buffer that has not actually been stored. This may 
not be the same as die ending index that was returned by die :new-output-buffer 
operation that was used to obtain diis buffer: if a :force-butput is being handled, 
ending-index indicates how much of die buffer is currently full. 

The method for diis operation should process die bufler's data and. if necessary, return 
the buffer to a free pool. 

jdlscard-output-buffer buffer-array Operation o//si:buffered-output-stream 

In a buffered output stream, diis operation is used as a subroutine of die standard output 
operations, such as :clear-output, to free an output buffer and say diat die data in it 
should be ignored. 

It should simply return bufferarray to a free pool, if appropriate. 

Some buffered output streams simply have one buffer array which they use over and over. 
For such streams, :new-output-buffer-can simply return that particular array each time; :send- 
output-buffer and :discard-output-buffer do not have to do anything about returning the buffer 
to a free pool. In fact, :discard-output-buffer can probably do nothing. 

si :buffered-stream Flavor 

'ITiis is a combination of si:buffered-input-stream and si;buffered-output-stream, used 
to make a buffered bidirectional stream. The input and output buffering are completely 
independent of each other. You must define all five of die low level operations: :new- 
output-buffer, .-send-output-buffer and :discard-output-buffer for output, and :next- 
input-buffer and :discard-input-buffer for input 

The data in most streams arc characters. Character streams should support either :line-in or 
:line-out in addition to the other standard operations. 

si: unbuff ered-llne-lnput-stream Flavor 

This flavor is the basis for unbuffered character input streams. You need only define :tyi 
and :untyi. 

si :11ne-output-stream-m1x1n Flavor 

To make an unbuffered character output stream, mix this flavor into the one you define, 
together with si:output-stream. In addition, you must define :tyo, as for unbuffered 
non-character streams. 
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s1 :buffered-1nput-chapacter-str0am Flavor 

This is used just like si:buffered-input-stream, but it also provides the :line-in operation 
and makes tcharacters return t. 

si :buffered-6utput-character-streara I’lavor 

This is used just like sirbuffered-output-stream, but it also provides the :line-out 
operation and makes rcharacters return t. 

si ibuffered-character-stream Flavor 

This is used just like siibuffered-stream, but it also provides the ;line-in and :line-out 
operations and makes xharacters return t. 

To make an unbulTered random-access stream, you need only define the :read-pointer and 
iset-pointer operations as appropriate. Since you provide the :tyi or :tyo handler yourself, the 
system cannot help you. 

In a buffered random-access stream, the random access operations must interact with the 
buffer management. ITie system provides for this. 

si: 1nput-po1nt®r-remember1ng-ffl1xin Flavor 

Incorporate this into a buffered input stream to support random access. ITiis flavor defines 
the ;read-pointer and :set-pointer operations. If you wish :set-pointer to work, you 
must provide a definition for the :set-buffer-pointer operation. You need not do so if 
you wish to support only tread-pointer. 

:set-buffer-pointer new-pointer Operation on sitinput-pointer-remembering-mixin 

You must define this operation if you use sitinput-pointer-remembering-mixin and want 
the :set-pointer operation to work. 

This operation should arrange for the next tnext-input-buffer operation to provide a 
bufferful of data that includes the specified character or byte position somewhere inside it. 

The value returned should be the file pointer corresponding to the first character or byte 
of that next bufferlul. 

si :output-po1nter-remember1ng-m1x1n Flavor 

Incorporate this into a buffered output stream to support random access. This mixin 
defines the :read-pointer and :set-pointer operations. If you wish :set-pointer to work, 
you must provide definitions for the ;set-buffer-pointer and :get-old-data operations. 
You need not do so if you wish to support only :read-pointer. 

: set-buffer-pointer Opera/Zon on si:output-pointer-remembering-mixin 

new-pointer 

This is the same as in si:input-pointer-remembering-mixin. 
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: get-old-data 0/;enj//Vw (wsi:output-pointer-remembering-mixin 

buffer-array lower-oulpuhlimil 

The buffer management routines perforin this operation when you do a :set-pointer tliat 
is outside the range of pointers that fit in the current output buffer, 'lliey first send tlic 
old buffer, tlien do :set-buffer-pointer as described above to say where in the file tlie 
next output buffer should come, tlien do mew-output-buffer to get the new buffer, 
fhen tlie ;get-old-data operation is performed. 

It should fill current buffer {buffer-array) with the old contents of tlie file at the 
corresponding addresses, so that wlicn tlie buffer is eventually written, any bytes skipped 
over by random iiccess will retain tlieir old values. 

'Phe instance variable si:stream-output-lower-|imit is tlie starting index in die buffer of 
die part that is supposed to be used for output. si:stream-output-limit is the ending 
index. The instance variable si :output-pointer-base is the file pointer corresponding to 
die starting index in die buffer. 

si :fne-stream-m1x1n Flavor 

Incorporate this mixin together with si:stream to make a file probe stream, which cannot 
do input or output but records the answers to an enquiry about a file. You should 
specify the init option :pathname when you instantiate the flavor. 

You must provide definitions for the iplist and rtruename operations: in terms of them, 
this mixin defines the operations :get, :creation-date, and :info. 

si: Input-flle-stream-mixin Flavor 

Incorporate this mixin into input streams that are used to read files. You should specify 
the file’s pathname with the pathname init option when you instantiate the flavor. 

In addidon to the services and requirements of si:file-stream-mixin, this mixin takes care 
of mentioning the file in the who-line. It also includes si:input-pointer-remembering- 
mixin so that the :read-pointer operation, at least, will be available. 

si :output-f ne-streain-m1x1n Flavor 

This is the analogue of si:input-fiie-stream-mixin for output streams, 

22.3.14 Implementing Streams Without Flavors 

You do not need to use flavors to implement a stream. Any object that can be used as a 
function, and decodes its first argument appropriately as an operation name, can serve as a 
stream. Although in practice using flavors is as easy as any other way, it is educational to see 
how to define streams “from scratch”. 

We could begin to define a simple output stream, which accepts characters and conses them 
onto a list, as follows: 
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(defvar the-list nil) 

(defun list output-stream (op Soptional argl &rest rest) 

(ecase op 
( :tyo 

(setq the-list (cons argl the-list))) 

(:which-operations ’(:tyo)))) 

This is an output stream, and so it supports the :tyo operation. All streams must support 
:which-operations. 

The lambda-list for a stream defined with a defun must always have one required parameter 
(op), one optional parameter (ari>/), and a rest parameter (res/). 

'I'his definition is not satisfactory, however. It handles :tyo properly, but it docs not handle 

:string-out, :direction, :send-if-handles, and other standard operations. 

'fhe function stream-default-handler exists to spare us the trouble of defining all those 
operations from scratch in simple streams like tliis. By adding one additional clause, we let the 
default handler take care of all other operations, if it can. 

(defun list-output-stream (op Soptional argl Sirest rest) 

(selectq op 
(:tyo 

(setq the-list (cons argl the-list))) 

(:which-operations ’(:tyo)) 

(otherwise 

(stream-default-handler #’list-output-stream 

op argl rest)))) 

If the operation is not one that the stream understands (c.g. :string-out), it calls stream- 
default-handler. Note how the rest argument is passed to it. lliis is why the argument list must 
look the way it does, stream-default-handler can be thought of as a restricted analogue of 
flavor inheritance. 

If we want to have only one stream of this sort, the symbol list-output-stream can be used 
as the stream. The data output to it will appear in the global value of the-list. One more step 
is required, though: 

(defprop list-output-stream t si:io-stream-p) 

This tells certain fimetions including read to treat the symbol list-output-stream as a stream 
rather than as an end of file option. 

If we wish to be able to create any number of list output streams, each accumulating its own 
list, we must use closures: 
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(defvar the-streain nil 

"Inside a list output stream, holds the stream itself.") 

(defvar the-list nil 

"Inside a list output stream, 
holds the list of characters being accumulated-.") 

(defun list-output-stream (op Sioptional argl &rest rest) 

(selectq op 
(:tyo 

(push argl the-list))) 

(:withdrawal (progl the-list (setq the-list nil))) 

(rwhich-operations ’(:tyo :withdrawal)) 

(otherwise 

(stream-default-handler the-stream 

op argl rest)))) 

(defun make-list-output-stream () 

(let ((the-stream the-list)) 

(setq the-stream 

(closure ’(the-stream the-list) 

’1ist-output-stream)))) 

We have added a new operation :withdrawal that can be used to find out what data has been 
accumulated by a stream. ITiis is necessary because we can no longer simply look at or set the 
global value of the-list: tliat is not the same as the value closed into the stteam. 

In addition, we have a new variable the-stream which allows the function list-output- 
stream to know which stream it is serving at any time. Ihis variable is passed to stream- 
default-handler so that when it simulates :string-out by means of :tyo, it can do the :tyo’s to 
the same stream that the :string-out was done to. 

The same stream could be defined with defselect instead of defun. It actually makes only a 
small difference. 'ITic defun for list-output-stream could be replaced with this code: 

(defselect (list-output-stream list-output-d-h) 

(:tyo (argl) 

(push argl the-list)) 

(:withdrawal () 

(progl the-list (setq the-list nil)))) 

(defun list-output-d-h (op &optional argl &rest rest) 
(stream-default-handler the-stream op argl rest)) 

defselect takes care of decoding the operations, provides a definition for :which-operations, 
and allows you to write a separate lambda list for each operation. 

By comparison, the same stream defined using flavors looks like this: 
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(defflavor list-output-stream ((the-list nil)) 

(si: 1ine-output-stream-mixin si:output-stream)) 

(defmethod (list-output-stream :tyo) (character) 

(push character the-list)) 

(defmethod (list-outut-stream :withdrawal) () 

(progl the-list (setq the-list nil))) 

(defun make-list-output-stream () 

(make-instance ’list-output-stream)) 

Here is a simple input stream, which generates successive characters of a list, 

(defvar the-list) :Put your input list here 

(defvar the-stream) 

(defvar untyied-char nil) 

(defun list-ihput-stream (op Soptional argl &rest rest) 

(selectq op 
(:tyi 

(cond ((not (null untyied-char)) 

(progl untyied-char (setq untyied-char nil))) 

((null the-list) 

(and argl (error argl))) 

(t (pop the-list)))) 

(:untyi 

(setq untyied-char argl)) 

(jwhich-operations ’(:tyi :untyi)) 

(otherwise 

(stream-defauIt-handler the-stream 

op argl rest)))) 

(defun make-list-input-streara (the-list) 

(let (the-stream untyied-char) 

(setq the-stream 

(closure ’(the-list the-stream untyied-char) 

’list-input-stream)))) 

The important things to note are that :untyi must be supported, and that the stream must 
check for having reached the end of the information and do the right thing with the argument to 
the :tyi operation. 

stream-defauU-handlep stream op argl rest 

Tries to handle the op operation on stream, given arguments of argl and the elements of 
rest. The exact action taken for each of the defined operations is explained with the 
documentation on that operation, above. 
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22.4 FormaUed Output 

'ilicrc arc two ways of doing general formatted output. One is the function format. 'I'hc 
other is tile output subsystem, format uses a control string written in a special format specifier 
language to control the output format. format:output provides l.isp functions to do output in 
particular formats. 

I'or simple tasks in which only the most basic fonnat specifiers arc needed, format is easy to 
use and has the advantage of brevity, b'or more complicated tasks, tlic format specifier language 
becomes obscure and hard to read. I’hcn formatioutput becomes advantageous because it works 
with ordinary Lisp control constructs. 

22.4.1 The Format Function 

format deslinalion control-siring &rcst args 

Produces formatted output, format outputs the characters of control-string, except tliat a 
tilde introduces a directive. The character after die tilde, possibly preceded by prefix 
parameters and modifiers, specifies what kind of formatting is desired. Most directives use 
one or more elements of args to create their output; the typical directive puts the next 
element of args into the output, formatted in some special way. 

The output is sent to destination. If destination is nil, a string is created which contains 
the output; this string is returned as the value of the call to format. In all other cases 
format returns no interesting value (generally it returns nil). If destination is a stream, the 
output is sent to it. If destination is t, the output is sent to ‘standard-output*. If 
destination is a string with an array-leader, such as would be acceptable to string-nconc 
(see page 216), the output is added to the end of that string. 

A directive consists of a tilde, optional prefix parameters separated by commas, optional colon 
(':’) and atsign (‘@’) modifiers, and a single character indicating what kind of directive this is. 
The alphabetic case of the character is ignored. The prefix parameters are generally decimal 
numbers. Examples of control strings: 

"~S” ; This is an S directive with no parameters. 

"~3,4:@s" ; This is an S directive with two parameters, 3 and 4, 

; and both the colon and atsign flags. 

, 4S " ; I'hc first prefix parameter is omitted and takes 

; on its default value, while the second is 4. 

format includes some extremely complicated and specialized features. It is not necessary to 
understand all or even most of its features to use format efficiently. The beginner should skip 
over anything in the following documentation that is not immediately useful or clear. The more 
sophisticated features are there for the convenience of programs with complicated formatting 
requirements. 

Sometimes a prefix parameter is used to specify a character, for instance the padding character 
in a right- or left-justifying operation. In this case a single quote (" ’") followed by the desired 
character may be used as a prefix parameter, so that you don’t have to know the decimal numeric 
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values of characters in the character set. For example, you can use "~5,’0d" instead of 
"~5,48d" to print a decimal number in five columns with leading zeros. 

In place of a prefix parameter to a directive, you can put the letter V, which u«kcs an 
argument from args as a parameter to the directive. Normally this should be a number but it 
doesn't really have to be. This feature allows variable column-widths and Uie like. Also, you can 
use the character # in place of a parameter; it represents the number of arguments remaining to 
be processed. 

Here arc some relatively simple examples to give you tlic general flavor of Itow format is 
used. 

(format nil "foo") => "foo” 

(setq X 5) 

(format nil "The answer is ~D," x) => "The answer is 5." 

(format nil "The answer is ~3D." x) => "The answer is 5." 

(setq y "elephant") 

(format nil "Look at the ~A!" y) => "Look at the elephant!" 

(format nil "The character ~:@C is strange." #\meta-beta) 

=> "The character Meta-^ (Greek-b) is strange." 

(setq n 3) 

(format nil "~D item~;P found." n) => "3 items found." 

(format nil "~R dog~;[s are~; is~] here." n (= n 1)) 

=> "three dogs are here." 

(format nil "~R dog~:*~[~l; is~;;s are~] here." n) 

=> "three dogs are here." 

(format nil "Here ~[~l;is~:;are~] ~:*~R pupp~:@P." n) 

=> "Here are three puppies." 

The directives will now be described, arg will be used to refer to the next argument from 
args. 

~A arg, any Lisp object, is printed without escaping (as by princ). ~:A prints () if arg is 
nil; this is useful when printing something that is always supposed to be a list '-nA 
inserts spaces on the right, if necessary, to make the column width at least n. The @ 
modifier causes the spaces to be inserted on the left rather than the riglit. 
~mincol.coIinc,ininpad,padcharA is the full form of ~A, which allows elaborate control 
of the padding. The string is padded on the right with at least minpad copies of 
padchar, padding characters are then inserted coUnc characters at a time until the total 
width is at least tnincol. The defaults are 0 for mincol and minpad, 1 for colinc, and 
space for padchar. 

~S This is just like ~A, but arg is printed with escaping (as by prini rather than princ). 

~D arg, a number, is printed in base ten. Unlike print, ~D never puts a decimal point 

after the number. ~«D uses a column width of n; spaces are inserted on the left if 
the number requires less than « columns for its digits and sign. If the number doesn’t 
fit in « columns, additional columns are used as needed. ~n,ntD uses m as the pad 
Character instead of space. If arg is not a number, it is printed in ~A format and 
decimal base. The @ modifier causes the number’s sign to be printed always; the 
default is only to print it if the number is negative. The : modifier causes commas to 
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be printed between groups of tltrec digits; the third prefix parameter may be used to 
change the character used as tiie comma. I’hus the most general fonn of ~D is 
~mincol,j)a(kluir,commacharD. 

~0 11118 is just like ~D but prints in (Ktal instead of decimal. 

~X This is just like ~D but prints in hex instead of decimal. Note that ~X used to have 

a difrercni meaning: print one or more spaces. Uses of ~X intended to have tliis 
meaning should be replaced with ~@T. 

~B This is just like ~D but prints in binary instead of decimal. 

~w,d,k,ovfl,pad? 

arg is printed in nonexponential floating point format, as in T0.5'. (If the magnitude 
of arg is very large or very small, it is printed in exponential notation.) 'llic 
parameters control the details of tiic formatting. 

w is the total field width desired. If omitted, this is not constrained. 

d is the number of digits to print after the decimal point. If d is omitted, it is 

chosen to do a good job based on w (if specified) and the value of arg. 

k is a scale factor, arg is multiplied by (exp 10. k) before it is printed. 

ovfl is a character to use for overflow. If arg is too big to print and fit the 

constraints of field width, etc., and ovfl is specified then the whole field is filled 
with ovfl. If o\fl is not specified, arg is printed using extra width as needed. 

pad is a character to use for padding on the left, when the field width is specified 
and not that many characters are really needed. 

If the @ modifier is used, a sign is printed even if arg is positive. 

Rational numbers are converted to floats and then printed. Anything else is printed 
with ~ivD format 

~w,d,e,k,ovfl,pad,exptE 

arg is printed in exponential notation, as in ‘.105e+2’. llie parameters control the 
details of the formatting. 

w is the total field width desired. If omitted, this is not constrained. 

(/and k 

control the number of mantissa digits and their arrangement around the decimal 
point, d+1 digits arc printed. If k is positive, all of them are significant 
digits, and the decimal point is printed after the first k of them. If k is zero 
or negative, the first |^|+1 of the d+1 digits are leading zeros, and the 
decimal point follows the first zero. (ITiis zero can be omitted if necessary to 
fit the number in w characters.) So the number of significant figures is less than 
(/ if A; is negative. 

The exponent printed always compensates for any powers of ten introduced 
according to k, so 10.5 might be printed as 0.105e + 2 or as 1050.0e-2. 
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If d is omitted, the system chooses enough significant figures to represent the 
float accurately. If k is omitted, the dctault is one. 

e is die number of digits to use for the exponent. If it is not specified, however 
many digits arc needed arc used. 

ovfl is the overflow character. If die exponent doesn't fit in e digits or the entire 
number does not fit in iv characters, then if ovfl is specified, the field of tv 
characters is filled with ovfl. Otherwise more characters arc used as needed. 

pad is a character to use for padding on the left, when the field width is specified 
and not diat many characters are really needed. 

expt is a character to use to separate the mantissa from the exponent. 'Ilic default is 
e or s or f, whichever would be used in printing the number normally. 

If the @ modifier is used, a sign is printed even if arg is positive. 

~w,d,e,k,ovfl,pad,expt Q 

Prints a floating point number arg in either ~F or ~E format. Fixed format is used if 
die absolute value of arg is less than (expt 10. J), and exponential format otherwise. 
(If d is not specified, it defaults based on the value of arg.) If fixed format is used, 
e + 2 blanks are printed at the end (where die exponent and its separator and sign 
would go, in exponential format). 1’hese count against the width w if that is specified. 
Four blanks are used if e is omitted. 7)ie diminished width available, d, ovfl and pad 

are used as specified. ITie scale factor used in fixed format is always zero, not k. 

If exponential format needs to be used, all the parameters arc passed to the ~E 
directive to print the number. 

Rational numbers are converted to floats and then printed. Anything else is printed 
with ~ivD format. 

~$ ~rdig,Idigfleld,padchar$ prints arg, a float, with exactiy rdig digits after the decimal 

point. The default for rdig is 2, which is convenient for printing amounts of money. 
At least Idig digits are printed preceding the decimal point; leading zeros are printed if 
there would be fewer than Idig. The default for Idig is 1. The number is right 
justified in a field field columns long, padded out with padchar. Ihe colon modifier 
means that the sign character is to be at the beginning of the field, before the 

padding, rather than just to the left of the number. The atsign modifier says that the 

sign character should always be output. 

If arg is not a number, or is unreasonably large, it is printed in ~field,„padchar@k 
format; i.e. it is prine’ed right-justified in the specified field width. 

(character arg) is put in the output, arg is treated as a keyboard character (see page 
206), thus it may contain extra control-bits. 'Ihese arc printed first by representing 
them with abbreviated prefixes: ‘C-’ for Control, ‘M-’ for Meta. ‘H-’ for Hyper, and 
‘S-’ for Super. 

With the colon flag (~:C), the names of the control bits arc spelled out (c.g. ‘Control- 
Meta-F’) and non-printing characters are represented by their names (e.g. ‘Return’) 
rather than being output as themselves. The printing characters Space and Altmode are 
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also represented as their names, but all others arc printed directly. 

With both colon and atsign (~:@C), the colon-only fonnat is printed, and tlicn if tlic 
character requires the Top or Greek (Front) shift kcy{s) to type it, tliis fact is 
mentioned (c.g. 'V (Top-U)’). I'his is the format used for telling die user about a key 
he is expected to type, for instance in prompt messages. 

For all three of these fonnats, if die character is a mouse character, it is printed as 
Mouse-, die name of the button, and die number of clicks. 

With just an atsign (~@C), die character is printed in such a way that the l.isp reader 
can understand it, using '#\' or depending on the escaping character of 

*readtable* (see page 516). 

~% Outputs a carriage return. ~h% outputs n carriage returns. No argument is used. 

Simply putting a carriage return in die control string would work, but ~% is usually 
used because it makes the control string look nicer in die Lisp source program. 

The :fresh-line operation is performed on the output stream. Unless the stream knows 
that it is already at the front of a line, this outputs a carriage return. ~/i& does a 
:fresh-line operation and then outputs n-\ carriage returns. 

~| Outputs a page separator character (#\page). ~/j| docs diis n times. With a : 

modifier, if the output stream supports the :clear-screen operation this directive clears 
the screen, otherwise it outputs page separator character(s) as if no : modifier were 
present. | is vertical bar, not capital I. 

— Outputs a tilde. ~n~ outputs n tildes. 

~ <CR> Tilde immediately followed by a carriage return ignores the carriage return and any 
whitespace at the beginning of the next line. With a the whitespace is left in place. 
With an @, the carriage return is left in place. This directive is typically used when a 
format control string is too long to fit nicely into one line of the program. 

arg vs ignored. ~n* ignores the next n arguments. “ignores backwards”: that is, 
it backs up in the list of arguments so that the argument last processed will be 
processed again. ~n\* backs up n\ arguments. ~«@* is absolute; it moves to 
argument /?(// = 0 specifics the first argument). 

When within a construct (sec below), the ignoring (in either direction) is relative to 
the list of arguments being processed by the iteration. 

~P If arg is not 1, a lower-case ‘s’ is printed. (‘P’ is for ‘plural’.) ~:P docs the same 
thing, after doing a that is, it prints a lower-case s if the last argument was not 
1. ~@P prints ‘y’ if the argument is 1, or ‘ies’ if it is not. ~:@P does the same 
thing, but backs up first 

~T Spaces over to a given column. ~«,mT outputs sufficient spaces to move the cursor to 
column n. If the cursor is already past column n, it outputs spaces to move it to 
column n + mk, for the smallest integer value k possible, n and m default to 1. 
Without the colon flag, n and m are in units of characters; with it, they are in units 
of pixels. 
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Note: this operation works properly only on streams tliat support tlic :read-cursorpos 
and lincrement-cursofpos stream operations (see page 467). On other streams, any 
~T operation simply ewtputs two spaces. When format is creating a string, ~T works 
by as.suming tliat the first character in tlic string is at die left margin. 

~@T simply outputs a space. ~re/T simply outputs rel spaces. ~rel, period T 
outputs rel spaces and then additional spaces until it reaches a column which is a 
multiple of period. If the output stream docs not support :read-cursorpos tlicn it 
simply outputs rel spaces. 

~R ~R prints arg as a cardinal English number, c.g. four. ~:R prints arg as an ordinal 

number, e g. fourth. ~@R prints arg as a Roman numeral, c.g. IV. ~:@R prints arg 
as an old Roman numeral, e.g. INI. 

~hR prints arg in radix n. 'nic flags and any remaining parameters are used as for 
die ~D directive. Indeed, ~D is the same as ~10R. Ihc full form here is therefore 
~ radix,itiincol,padchar,commacharF{. 

~? Uses up two arguments, and processes die first one as a format control string using the 

second one’s elements as arguments. 'Phus, 

(format nil "~? ~D" "~0 ~0" ’(4 20.) 9) 
returns "4 24 9". 

~@? processes the following argument as a format control string, using all the 
remaining arguments. Any arguments it docs not use arc left to be processed by the 
format directives following the ~@? in the original control string. 

(format nil "~@? ~D" "~0 ~0" 4 20. 9) 
likewise returns "4 24 9". 

~-*s(r~*- Performs the formatting specified by sir, with indentation on any new lines. Each 
time a Return is printed during the processing of sir, it is followed by indentation 
sufficient to line up underneath the place where the cursor was at the beginning of sir . 
For example, 

(format t "Foo: siring) 

prints siring with each line starting at column 8. If siring is (string-append "This is" 
#\return "the string") then the output is 
Foo: This is 

the string 

~{sir~) Performs output with case conversion. The formatting specified by sir is done, with all 
the letters in the resulting output being converted to upper or lower case according to 
the modifiers given to the ~( command: 

~( without modifiers 

Converts all the letters to lower case. 

~:( Converts the first letter of each word to upper case and the rest to lower case. 

~@( Converts the first letter of the first word to upper case, and all other letters to 

lower case. 

Converts all the letters to upper case. 
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~1( Converts iJie first letter of the first word to upper case and docs not change 
anything else. If you arrange to generate all output in lower case except for 
letters tliat should be upper case regardless of context, you can use tiiis 
directive when the output appears at die beginning of a sentence. 

Example: 

”~(FoO BaR~) ~:{FoO BaR~) ~@(FoO BaR~) ~:@(FoO BaR~) 

~l(at the White Hart~)" 
produces 

foo bar Foo Bar Foo bar FOO BAR 
At the White Hart 

This is a set of alternative control strings. ’I'he alternatives (called clauses) are 
separated by and the construct is tenninated by For example, 

"~[Siamese ~;Manx ~;Persian ~;Tortoise-Shell ~ 

~;Tiger ~;Yu-Shiang ~]kitty" 

'I’he argtin alternative is selected; 0 selects die first. If a prefix parameter is given (i.e. 
~/;[). tiien the parameter is used instead of an argument (this is useful only if the 
parameter is *#’). If arg is out of range no alternative is selected. After the selected 
alternative has been processed, the control string continues after the ~]. 

~[strO~;slrl~;...~-,slrn~:;defauIl'^] has a default case. If the last used to separate 
clauses is instead then the last clause is an “else” clause, which is performed if no 
other clause is selected. For example, 

"~[Siamese ~;Manx ~;Persian ~;Tiger ~ 

"jYu-Shiang ~:;Bad ~] kitty" 

~[~tagOO,tagOI ,...;strO~iagIO,tagIl ,...\strl...~] allows the clauses to have explicit tags. 
The parameters to each arc numeric tags for the clause which follows it That 
clause is processed which has a tag matching the argument If ~al,a2,bl,b2,„.:; (note 
the colon) is used, then the following clause is tagged not by single values but by 
ranges of values al through a2 (inclusive), bl dirough b2, etc. with no 

parameters may be used at the end to denote a default clause. For example, 

’//;operator A,’Z,’a,’z:;letter ~ 

~’0,’9:;digit ~:;other ~]" 

~’\false~\irue~] selects the false control string if arg is nil, and selects the true control 
string otherwise. 

tests the argument. If it is not nil, then the argument is not used up, but 

is the next one to be processed, and the one clause is processed. If it is nil, then the 

argument is used up, and the clause is not processed. For example, 

(setq *print-level* nil *print-length* 5) 

(format nil 

•PRINT-LEVEL*=~D~]~@[ •PRINT-LENGTH*=~D~]" 
prinlevel prinlength) 

»> " •PRINT-LENGTH*=5" 
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The combination of ~[ aitd # is useful, for example, for dealing with Hnglish 
conventions for printing lists: 

(setq foo "Items:~#[ none~; ~S~: ~S and ~ 

and-] 

(format nil foo) 

=> "Items: none." 

(format nil foo ’foo) 

=> "Items: FOO." 

(format nil foo ’foo ’bar) 

=> "Items: FOO and BAR." 

(format nil foo ’foo ’bar ’baz) 

=> "Items: FOO, BAR, and BAZ." 

(format nil foo ’foo ’bar ’baz ’quux) 

=> "Items: FOO, BAR, BAZ, and QUUX." 

Separates clauses in ~[ and ~< constnictions. It is undefined elsewhere. 

~] Terminates a ~[. It is undefined elsewhere. 

This is an iteration construct. ITie argument should be a list, which is used as a set of 
arguments as if for a recursive call to format. ITie string sir is used repeatedly as the 
control string. Each iteration can absorb as many elements of the list as it likes; if sir 
uses up two arguments by itself, then two elements of the list get used up each time 
around the loop. If before any iteration step the list is empty, then the iteration is 
terminated. Also, if a prefix parameter « is given, then there can be at most n 
repetitions of processing of sir. Here are some simple examples: 

(format nil "Here it is:~{ -S-}." ’(a b c)) 

=> "Here it is: A B C." 

(format nil "Pairs of things<~S,~S>~}." ’(a 1 b 2 c 3)) 
=> "Pairs of things: <A,1> <B,2> <C,3>." 

Using as well, to terminate sir if no arguments remain, we can print a list with 
commas between the elements: 

(format nil "Elements: ’(a b c)) 

=> "Elements: A, B, C." 

is similar, but die argument should be a list of sublists. At each repetition 
step one sublist is used as the set of arguments for processing sir; on the next 
repetition a new sublist is used, whether or not all of the last sublist had been 
processed. Example: 

(format nil "Pairs of things:~:{ <~S,~S>~}." 

’((a 1) (b 2) (c 3))) 

=> "Pairs of things: <A,1> <B,2> <C,3>." 

is similar to -{s/r-}, but instead of using one argument which is a list, 
all ^e remaining arguments are used as the list of arguments for the iteration. 
Example: 


PS:<1 ..M AN>F1>FI0.TEXT.24 


8-JUN-84 



I isp Machine Manual 


491 


l•■()|•mallcd Output 


(format nil "Pairs of things:~@{ <~S,~S>~)." 

’a 1 'b 2 ’c 3) 

=> "Pairs of things: <A,1> <B,2> <C,3>." 

combines the features of aiid All the remaining 

arguments are used, and each one must be a list. On each iteration tlie next argument 
is used as a list of arguments to sir. Example: 

(format nil "Pairs of things:~:@{ <~S,~S>~}." 

’(a 1) ’(b 2) ’(c 3)) 

=> "Pairs of things: <A,1> <B,2> <C,3>." 

I'erminaiing tlie repetition construct with instead of forces sir to be processed 
at least once even if the initial list of arguments is null (however, it does not override 
an explicit prefix parameter of zero). 

If sir is empty, then an argument is used as sir. It must be a string, and precedes 
any arguments processed by the iteration. As an example, the following are 
equivalent: 

(apply ^’format stream string args) 

(format stream string args) 

This uses string as a formatting string. ITie ~1{ says it must be processed at most 
once, and the ~:) says it must be processed at least once. Therefore it is proeessed 
exaetly once, using args as the arguments. 

As another example, the format function itself uses format-error (a routine internal to 
tlie format paekage) to signal error messages, which in turn uses terror, which uses 
format recursively. Now format-error takes a string and arguments, just like format, 
but also prints some additional infonnation: if the control string in ctl-string actually 
is a string (it might be a list—sec below), then it prints the string and a little arrow 
showing where in the processing of the control string the error occurred. The variable 
ctl-index points one character after the place of the error. 

(defun format-error (string &rest args) 

(if (stringp ctl-string) 

(ferror nil "~l{~:}~%~VT^~%~3@T/"~A/"~%" 

string args (+ ctl-index 3) ctl-string) 

(ferror nil string args))) 

This first processes the given string and arguments using then tabs a variable 

amount for printing the down-arrow, then prints the control siring between double¬ 
quotes. llie effect is something like this: 

(format t "The item is a ~[Foo~;Bar~;Loser~]." ’quux) 
»ERR0R: The argument to the FORMAT command 

must be a number 

4 - 

"The item is a ~[Foo~;Bar~;Loser~]." 

Terminates a It is undefined elsewhere. 

~< ~mincoi,coIinc,nunpad,padchar<lexl~'> justifies text within a field at least mincol wide. 

tex! may be divided up into segments with —the spacing is evenly divided between 
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tlic text segments. With no modifiers, tiie leftmost text segment is left justified in tlic 
field, and the rightmost text segment right justified: if there is only one. as a special 
case, it is right justified. 'I'hc : modifier causes spacing to be introduced before Uie 
first text segment; tlie @ modifier causes spacing to be added after tltc last. Minpad, 
default 0. is tlie minimum number of padchar (default space) padding characters to be 
output between each segment. If the total width needed to satisfy these constraints is 
greater than mincol, then inincol is adjusted upwards in colinc increments, colinc 

"foo bar" 

" foo bar" 

" foo bar " 

" foobar" 

" foobar" 
"foobar " 

" foobar " 

'•$*♦*♦**2.59" 


defaults to 1. miiicol defiiults to 0. For example, 

(format nil "~10<foo~;bar~>") => 
(format nil "~10:<foo~;bar~>") => 
(format nil "~10:@<foo~:bar~>") => 
(format nil "~10<foobar~>") => 
(format nil "~10:<foobar~>") => 
(format nil "~10@<foobai—>") => 
(format nil "~10:@<foobar~>") => 
(format nil "$~10,.,’♦<~3f~>" 2.5902) => 


Note that text may include format directives. ITie last example illustrates how the ~< 
directive can be combined with the ~f directive to provide more advanced control over 
die formatting of numbers. 

Here are some examples of the use of within a ~< construct is explained in 
detail below, however the general idea' is that it eliminates the segment in which it 
appears and all following segments if there are no more arguments. 

(format nil "~15<~S~;~''~S~;~''~S~>" ’foo) 

=> " FOO" 

(format nil ’foo ’bar) 

=> "FOO BAR" 

(format nil "~15<~S~;-’foo ’bar ’baz) 

=> "FOO BAR BAZ" 

The idea is that if a segment contains a and format runs out of arguments, it just 
stops there instead of getting an error, and it as well as the rest of the segments are 
ignored. 

If the first clause of a ~< is terminated with instead of then it is used in a 
special way. All of the clauses are processed (subject to of course), but the first 
one is omitted in performing the spacing and padding. When the padded result has 
been determined, then if it will fit on the current line of output, it is output, and the 
text for the first clause is discarded. If, however, the padded text will not fit on the 
current line, then the text segment for the first clause is output before the padded text. 
The first clause ought to contain a carriage return (~%). The first clause is always 
processed, and so any arguments it refers to will be used; the decision is whether to 
use the resulting segment of text, not whether to process the first clause. If the 
has a prefix parameter n, then the padded text must fit on the current line with n 
character positions to spare to avoid outputting the first clause’s text. For example, the 
control string 

can be used to print a list of items separated by commas, without breaking items over 
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line boundaries, and beginning each line with I he prefix parameter 1 in ~ 

accounts for tile width oFthc-comma which will follow the justified item if it is not 
die last element in Uie list, or the period if it is. If has a second prefix 
parameter. Uien it is used as the width of the line. Unis overriding the natural line 
width of the output stream. Jo make the preceding example use a line width ot 5U. 

one would write 


If die second argument is not specified, then format sees whether die stream handles 
die :size-in-characters message. If it docs, dicn format sends diat message and uses 
the first returned value as the line length in characters. If it doesn't, format uses 72. 
as die line length. 

Rather than using this complicated syntax, one can often call the function 
formatrprint-list (see page 495). 

~> Terminates a ~<. It is undefined elsewhere. 

Ihis is an escape construct. If there are no more arguments remaining to be processed, 
dien the immediately enclosing or ~< construct is terminated. If there is no such 
enclosing construct, dien the entire formatting operation is terminated. In the ~< case, 
the formatting is performed, but no more segments arc processed before doing the 
jusdfication. 'ITie should appear only at the beginning of a ~< clause, because it 
aborts the entire clause. may appear anywhere in a construct 


If a prefix parameter is given, then termination occurs if the parameter is zero. 
(Hence is the same as -#".) If two parameters are given, termination occurs if 
they are equal. If three are given, termination occurs if the second is between the 
other two in ascending order. Of course, this is useless if all die prefix parameters are 
constants; at least one of diem should be a # or a V parameter. 


If is used within a construct, then it merely terminates the current iteration 
step (because in the standard case it tests for remaining arguments of the current step 
only); the next iteration step commences immediately. To terminate the enUre iteration 

process, use ~r. 

An escape to arbitrary user-supplied code, arg is called as a function; its arguments 
arc the prefix parameters to ~Q, if any. args can be passed to the function by using 
the V prefix parameter. The function may output to * standard-output* and may look 
at the variables format:colon-flag and format:atsign-flag, which are t or ml to reflect 
the : and @ modifiers on the ~Q. For example, 

(format t "~VQ" foo bar) 
is a fancy way to say 

(funcall bar foo) ^ r ^ 

and discard the value. Note the reversal of order; the V is processed before the Q. 

This begins a directive whose name is longer than one character. The name is 
terminated by another \ character. ITie following directives have names longer than 
one character and make use of the ~\ mechanism as part of their operation. 


PS:<L.MAN>H>FIO.TEXT.24 


8-JUN-84 



494 


I'orniaticd Ouipiil 


I .isp Machine Manual 


~\lozenged-stringX 

This is like ~A except when output is to a window, in which case the argument is 
printed in a small font inside a lozenge. 

~\lozenged-character\ 

This is like ~C except when output is to a window, in which case the argument is 
printed in a small font inside a lozenge if it has a character name, even if it is a 
fonnatting character or graphic character. 


~\date\ This expects an argument that is a universal time (see page 776), and prints it as a 
date and time using time:print-universal-date. 

Hxamplc: 

(format t "It is now ~\date\" ( get-uni versal-time)) 

prints 

It is now Saturday the fourth of December, 1982; 4:00:32 am 

~\time\ This expects an argument that is a universal time (see page 776), and prints it in a 
brief format using time:print-universal-time. 

Example: 

(format t "It is now ^\time\" (get-universal-time)) 

prints 

It is now 12/04/82 04:01:38 


~\datime\ 

This prints the current time and date. It docs not use an argument. It is equivalent to 
using the ~\time\ directive with (time:get-universal-time) as argument. 

~\time-interval\ 

'fhis prints a time interval measured in seconds using tlie function tlme:print-interval- 
or-never. 

Example: 

(format t "It took ~\time-interval\." 3601.) 

prints 

It took 1 hour 1 second. 

You can define your own directives. How to do this is not documented here; read the code. 
Names of user-defined directives longer than one character may be used if they are enclosed in 
backslashes (e.g. ~4,3\GRAPH\). 

(Note: format also allow'S wntrohstring to be a list If the list is a list of one clement, 
which is a string, the string is simply printed. This is for the use of the format:outfmt function 
below. The old feature wherein a more complex interpretation of this list was possible is now 
considered obsolete; use format:output if you like using lists.) 

A condition instance can also be used as the control-string. Then the ;report operation is 
used to print the condition instance; any other arguments are ignored. 'Ihis way, you can pass a 
condition instance directly to any function that normally expects a format string and arguments. 
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forraat:pr1nt-Hst dcsiinalion elcinenl-fomial list &optional separator start-line 
tUde-brace-options 

This function provides a simpler interface for tlic specific purpose of printing comma- 
separated lists with no list clement split across two lines; sec the description of the 
directive (page 492) to sec the more complex way to do this within format, destination 
tells where to send the output: it can be t, nil. a string-nconc’ablc siring, or a stream, 
as with format, elenwnt-fonnat is a format control-string tliat tells how to print each 
clement of list: it is used as the body of a ctmstruct. separator, which defaults 

to "," (comma, space) is a string which goes after each clement except the last, format 
control commands arc not recommended in separator, start-line, which defaults to three 
spaces, is a format control-string that is used as a prefix at the beginning of each line of 
output, except the first, format control commands arc allowed in separator, but they 
should not swallow arguments from list, tilde-brace-options is a string inserted before the 
opening it defaults to the null string, but allows you to insert colon and/or atsign. 
I’he line-width of the stream is computed the same way tliat the command computes 
it; it is not possible to override tlic natural line-width of the stream. 
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22.4.2 The Output Subsystem 

nic formatting functions associated with the format:output subsystem allow you to do 
formatted output using Lisp-style control structure. Instead of a directive in a format control 
string, tliere is one formatting function for each kind of formatted output. 

'I’hc calling conventions of most of the fonnatting functions arc similar. 'I'hc first argument is 
usually the datum to be output. The second argument is usually the minimum number of 
columns to use. The remaining arguments are keyword arguments. 

Most of die flinctions accept the keyword arguments padchar, minpad and lab-period, padchar 
is a character to use for padding, minpad is a minimum number of padding characters to output 
after die data, lab-period is die disuincc between allowable places to stop padding. lo make the 
meaning of lab-period clearer, if the value of lab-period is 5, if the minimum size of the field is 
10, and if die value of tninpad is 2, then a datum diat takes 9 characters is padded out to 15 
characters. The requirement to use at least two characters of padding means it can't fit into 10 
characters, and die lab-period of 5 means the next allowable stopping place is at 10+5 characters, 
riie default values for minpad and lab-period, if they are not specified, arc zero and one. ITie 
dcfiiult value for padchar is space. 

The formatting functions always output to ‘standard-output* and do not require an 
argument to specify the stream. The macro format:output allows you to specify the stream or a 
string, just as format docs, and also makes it convenient to concatenate constant and variable 
output. 

format:output stream slring-orform... Macro 

Makes it convenient to intersperse arbitrary output operations with printing of constant 
strings, ‘standard-output* is bound to stream, and each siring-orfonn is processed in 
succession from left to right. If it is a string, it is printed; otherwise it is a form, which 
is evaluated for effect. Presumably the forms will send output to ‘standard-output*. 

If stream is written as nil, then the output is put into a string which is returned by 
formaf.output. If stream is written as t, then the output goes to the prevailing value of 
‘standard-output*. Otherwise stream is a form, which must evaluate to a stream. 

Here is an example: 

(format:output t "FOO is " (prinl foo) " now." (terpri)) 

Because format:output is a macro, what matters about stream is not whether it evaluates 
to t or nil, but whether it is actually written as t or nil. 

format :outfmt siring-orform... Macro 

Some system functions ask for a format control string and arguments, to be printed later. 
If you wish to generate the output using the formatted output functions, you can use 
formatioutfmt, which produces a control argument that will eventually make format print 
the desired output (this is a list whose one element is a string containing the output). A 
call to format:outfmt can be used as the second argument to terror, for example; 
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(ferror nil (format:outfmt "Foo is " (format:onum foo) 

" which is too large”)) 

format ronum number &optional radix minwidlh &kcy padchar miupad tab-period signed 
commas 

Outputs number in base radix, padding to at least //////hvV//// columns and obeying Uie 
other padding options specified as described above. 

radix can be a number, or it can be troman, lenglish, or :ordinal. The default radix is 
10. (decimal). 

If signed is non-nil, a + sign is printed if tlic number is positive. If commas is non-nil, 
a comma is printed every third digit in tlic customary way. Hicsc arguments arc 
meaningful only with numeric radices. 

format refloat number &optional n-digits force-exponential-notation minwidth &kcy padchar 
minpad tab-period 

Outputs number as a floating point number using n-digits digits. If force-exponential- 
notation is non-nil, then an exponent is always used, minwidth and the padding options 
arc interpreted as usual. 

formatrostring string Aoptional minwidth &key padchar minpad tab-period right-justify 

Outputs s/rwg, padding to at least minwidth columns if minwidth is not nil, and obeying 
the other padding options specified as described above. 

Normally the data are left justified; any padding follows the data. If right-justify is non- 
nil, the padding comes before the data. The amount of padding is not affected. 

The argument need not really be a string. Any Lisp object is allowed, and it is output 
with princ. 

formatroprlnt object &optional minwidth &key padchar minpad tab-period right-justify 

Prints object, any Lisp object, padding to at least minwidth columns if minwidth is not nil, 
and obeying the padding options specified as described above. 

Normally the data are left justified; any padding follows the data. If right-justify is non- 
nil, the padding comes before the data. The amount of padding is not affected. 

The printing of the object is done with prinl. 

format :ochar character &optional style top-explain minwidth &key padchar minpad 
tab-period 

Outputs character in one of three styles, selected by the style argument, minwidth and the 
padding options control padding as usual. 

ireadornil The character is printed using #\ or #/ so that it could be read back 
in. 

:editor Output is in the style of‘Meta-Rubout’. Non-printing characters, and the 

two printing characters Space and Altmodc, arc represented by their 
names. Other printing characters are printed directly. 
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Brief prefixes such as ‘C-’ and 'M-' arc used, rallicr titan ‘Control-’ or 
‘Meta-’. Alst), character names arc used only if llicrc arc incta bits 
present. 

I'hc output is the same as that of the :editor style, but If tlie character is 
not a graphic character or if it has meta bits, and the stream supports the 
idisplay-lozenged-string operation, that operation is used instead of 
:string-out to print the text. On windows this operation puts the 
character name inside a lozenge. 

:sail ‘rt’, ”, etc. arc used to represent Control and Meta, and shorter names 

for characters arc also used when possible. See section 10.1.1, page 205. 

toi)-explain is useful with the :editor. :brief and :sail styles. It stiys that any character 

diat has to be typed using the lop or Greek keys should be followed by an explanation 

of how to type it. For example: (Top-K)’ or ’« (Greek-a)’. 

format:tab mincol &key padchar minpad tab-period terpri unit 

Outputs padding at least until column //twco/. It is the only formatting function that 

bases its actions on the actual cursor position rather than the width of what is being 

output. I'hc padding options padchar, minpad, and tab-period arc obeyed. 'I'hus, at least 
the minpad number of padding characters are output even if that goes past mincol, and 
once past mincol, padding can only stop at a multiple of tab-period characters past 
mincol. 

In addition, if the terpri option is t, then if column mincol is passed, format:tab starts a 
new line and indents it to mincol. 

The unit option specifics the units of horizontal position. The default is to count in units 
of characters. If unit is specified as -.pixel, then the computation (and the argument 
mincol and the minpad and tab-period options) are in units of pixels. 

format:pad {minwidth &kcy padchar minpad tab-period...) body... Macro 

format:pad is used for printing several items in a fixed amount of horizontal space, 
padding between them to use up any excess space. Each of the body forms prints one 
item. The padding goes between items. The entire format:pad always uses at least 
minwidth columns; any columns that the items don’t need arc distributed as padding 
between the items. If that isn’t enough space, then more space is allocated in units 
controlled by the tab-period option until there is enough space. If it’s more than enough, 
the excess is used as padding. 

If the minpad option is specified, then at least that many pad characters must go between 
each pair of items. 

Padding goes only between items. If you want to treat several actual pieces of output as 
one item, put a progn around them. If you want padding before the first item or after 
the last, as well as between the items, include a dummy item nil at the beginning or the 
end. 


ibrief 


ilozenged 
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If there is only one item, it is right justified. One item followed by nil is left-justified. 
One item preceded and followed by nil is centered. I'hcrcfore, format:pad can be used 
to provide tlic usual padding options for a function tliat docs not provide them itself. 

format:plural number singular &optional plural 

Outputs either the singular or the plural form of a word depending on die value of 
number. The singular is used if and only if number is 1. singular specifics the singular 
form of the word, string-pluralize is used to compute die plural, unless plural is 
explicitly specified. 

It is often useful for number to be a value returned by format:onum, which returns its 
argument, l-or example: 

(format:plural (format:onum n-frobs) ” frob") 
prints "1 frob" or "2 frobs". 

format:breakline linel prinHf-terpri print-always... Macro 

Goes to the next line if diere is not enough room for something to be output on the 
current line. The print-always forms print the text which is supposed to fit on the line. 
Unel is the column before which the text must end. If it doesn’t end before that column, 
then format:breakline moves to the next line and executes the print-if-terpri form before 
doing the print-always forms. 

Constant strings arc allowed as well as forms for print-if-terpri and print-always. A 
constant string is just printed. 

To go to a new line unconditionally, simply call terpri. 

Here is an example that prints the elements of a list, separated by commas, breaking lines 
between elements when necessary. 

(defun pci (list linel) 

(do ({1 list (edr 1))) ((null 1)) 

(formatrbreakline linel " " 

(princ (car 1)) 

(and (edr 1) (princ ", "))))) 
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22.5 Rubout Handling 

riic rubout handler is a feature of all interactive streams, that is. streams that connect to 
terminals. Its purpose is to allow the user to edit minor mistakes made during type-in. At the 
same time, it is not supposed ii> get in the way: input is to be seen by l.isp as soon as a 
syntactically complete form has been typed. 'I'hc definition of ‘synuictically complete form’ 
depends on the function Uiat is reading from tlic stream; for read, it is a l.isp expression. 

Some interactive streams (‘editing l.isp listeners') have a rubout handler that allows input to 
be edited with the full power of tlic ZWl-l editor. (ZWHI is the general editor implementation 
on which Zmacs and /.Mail arc based.) Most windows have a rubout handler that apes ZWld, 
implementing about twenty common ZWId commands. The cold load stream has a simple rubout 
handler lliat allows just rubbing out of single characters, and a few simple commands like clearing 
ilic screen and erasing the entire input typed so far. All Uircc kinds of rubout handler use the 
same proUKol, which is described in this section. Wc also Sity a little about die most common of 
the three rubout handlers. 

[Rvcntually some version of ZWEl will be used for all streams except the cold load stream] 

The tricky thing about the rubout handler is the need for it to figure out when you are all 
done. The idea of a rubout handler is diat you can type in characters, and Uicy are saved up in 
a buffer so that if you change your mind, you can rub them out and type different characters. 
However, at some point, the rubout handler has to decide that the time has come to stop putting 
characters into the buffer and to let the function parsing the input, such as read, return. I'his is 
called aciivaiion. 'Hie right time to activate depends on die function calling the rubout handler, 
and may be very complicated (if the function is read, figuring out when one Lisp expression has 
been typed requires knowledge of all the various printed representadons, what all currently-defined 
reader macros do, and so on). Rubout handlers should not have to know how to parse the 
characters in the buffer to figure out what die caller is reading and when to activate; only the 
caller should have to know this. ITie rubout handler interface is organized so that the calling 
function can do all the parsing, while the rubout handler does all the handling of editing 
commands, and the two arc kept completely separate. 

The basic way that the rubout handler works is as follows. When an input function that reads 
characters from a stream, such as read or readline (but not tyi), is invoked with a stream which 
has rrubout-handler in its :which-operations list, that function “enters” the rubout handler. It 
then goes ahead :tyi’ing characters from the stream. Because control is inside the rubout handler, 
the stream echoes these characters so the user can see what he is typing. (Normally echoing is 
considered to be a higher-level ftinction outside of the province of streams, but when the higher- 
level function tells the stream to enter the rubout handler it is also handing it the responsibility 
for echoing.) I’hc rubout handler is also saving all these characters in a buffer, for reasons 
disclosed in the following paragraph. When the parsing function decides it has enough input, it 
returns and control “leaves” the rubout handler. This is the easy case. 

If the user types a rubout, a throw is done out of all recursive levels of read, reader macros, 
and so forth, back to the point where the rubout handler was entered. Also the rubout is echoed 
by erasing from the screen the character which was rubbed out. Now the read is tried over 
again, re-reading all the characters that have not been rubbed out, not echoing them this time. 
When the saved characters have been exhausted, additional input is read from the user in the 
usual fashion. 
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The effect of Uiis is a coniplcic separation of the functions of rubout handling and parsing, 
while at the same time mingling die execution of these two functions in such a way that input is 
always activated at just die right time. It docs mean that the parsing function (in die usual ease, 
read and all macro-character definitions) must be prepared to be thrown through at any time and 
should not have non-trivial side-effects, since it may be called midtiple dmes. 

If an error occurs while inside the rubout handler, the error message is printed and then 
additional characters are read. When the user types a rubout, it rubs out the error message as 
well as the character that caused the error. The user can dien proceed to type die corrected 
expression; the input will be reparsed from the beginning in the usual fiishion. 

The nibout handler based on die ZWHI editor interprets control characters in die usual ZWEl 
way: as editing commands, allowing you to edit your buffered input. 

'fhe common rubout handler also recognizes a subset of die editor commands, including 
Rubout, Controi-F and Meta-F and others. Typing Help while in the rubout handler displays a 
list of die commands. The kill and yank commands in the rubout handler use die same kill ring 
as the editor, so you can kill an expression in the editor and yank it back into a rubout handler 
with Control-Y, or kill an expression in the rubout handler with Control-K or Clear-input and 
yank it back in the editor. 'Hie rubout puKessor also keeps a ring buffer of most recent input 
strings (a separate ring for each stream), and the commands Control-C and Meta-C retrieve from 
this ring just as Control-Y and Meta-Y do from the kill ring. 

When not inside the rubout handler, and when typing at a program that uses control 
characters for its own purposes, control characters are treated the same as ordinary characters. 

Some programs such as die debugger allow the user to type either a control character or an 
expression. In such programs, you are really not inside the rubout handler unless you have typed 
the beginning of an expression. When the input buffer is empty, a control character is treated as 
a command for the program (such as, Control-C to continue in the debugger); when there is 
text in the rubout handler buffer, the same character is treated as a rubout handler command. 
Another consequence of this is that the message you get by typing Help varies, being either the 
rubout handler s documentation or the debugger’s documentation. 

To write a parsing function that reads with rubout handling, use with-input-editIng. 

wlth-lnput-edltlng {stream options) body... Macro 

Invokes the rubout handler on stream, if stream supports it, and then executes body, 
body is executed in any case, within the rubout handler if possible, rubout-handler is 
non-nil while in body if rubout handling is in use. 

options are used as the rubout handler options. If already within an invocation of the 
rubout handler, options are appended to the front of the options already in effect. This 
happens if a function which reads input using with-input-editing, such as read or 
readline, is called from the body of another with-input-editing, I'he :norecursive 
option can be used to cause the outer set of options to be completely ignored even when 
not overridden by new ones. 
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body\ values are returned by with-input-editing, body ought to read input from stream 
and return a Lisp object that represents the input It should have no nontrivial side 
effects aside from reading input from stream structure, as it may be aborted at any time it 
reads input and may be executed over and over. 

If the :full-rubout option is specified, and the user types some input and rubs it all out, 
the with-input-editing fonn returns immediately. Sec :full-rubout, below. 

If a preemptive command is input by the user, with-input-editing returns immediately 
with the values being as specified below under Uic rcommand and :preemptable options. 
body is abtJrtcd from its call to tlie :tyi operation, and Uic input read so far remains in 
tltc rubout handler editing buffer to be read later. 


rubout-handler Variable 

If control is inside tlic rubout handler in this process, the value is the stream on which 
rubout handling is being done. Otherwise, the value is nil. 


:rubout-handler options function &rcst args Operation on streams 

Invokes the nibout handler on the stream, with options as the options, and parses by 
applying yi//ic//on to args. with-input-editing uses this operation. 


: re ad - bp Operation on streams 

This operation may be used only from within the code for parsing input from this stre^ 
inside the rubout handler. It returns the index within the rubout handler buffer which 
parsing has reached. 

: force-rescan Operation on streams 

This operation may be used only from within the code for parsing input from this stream 
inside the rubout handler. It causes parsing to start again immediately from the beginning 
of the buffer. 

;rescann1ng-p Operation on streams 

This operation may be used only from within the code for parsing input from this stream 
inside the rubout handler. It returns t if parsing is now being done on input already in 
the buffer, nil if parsing has used up all the buffered input and the next character parsed 
will come from the keyboard. 

Each option in the list of rubout handler options consists of a list whose first element is a 
keyword and whose remaining elements are the arguments of that keyword. Note that this is not 
the same format as the arguments to a typical function that takes keyword arguments, rather this 
is an alist of options, lire standard options are: 

(•.activation yh args...) 

Activate if certain characters are typed in. When the user types an 
activation character, the rubout handler moves the editing pointer 
immediately to the end of the buffer and inserts the activation character; 
This immediately causes the parsing function to begin rescanning the 
input 
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fn is used to test charactefs for being activators, it is called with an input 
character as die first arg (possibly a fixnum, possibly a character object) 
and args as additional args. If fn returns non-nil, the character is an 
activation, fn is not called for blips, 

After die parsing funetion has read die entire contents of the buffer, it 
secs the activation character as a blip (:activation char numerk-ars) where 
char is die character diat activated and nunteric-arg is the numeric arg that 
was pending for the next rubout handler cominaiid. Nonnally the parsing 
function will return at this point, riicn die activation character docs not 
echo. But if die parsing function continues to read input, die activation 
character echoes and is inserted in the buffer. 

(:do-not-echo chars...) 

Poor man's activation characters. Like ractivation except diat the 
characters that should activate arc listed explicitly, and the character itself 
is returned to die parsing function rather than a blip. 

{:full-rubout val) 

If the user rubs out all the characters he typed, then control is returned 
from die rubout handler immediately. Two values are returned; the first 
is nil and the second is val. (If die user doesn’t rub out all the 
characters, then the rubout handler propagates multiple values back from 
the function that it calls, as usual.) In the absence of this option, the 
rubout handler would simply wait for more characters to be typed in and 
would ignore any addiUonal rubouts. 

This is how the debugger knows to remove Eval: from the screen if you 
type die beginning of a form and rub it all out. 

(:pass-through charl char2...) 

The characters charl, charl, etc. arc not to be treated as special by the 
rubout handler. They are read as input by the parsing function. If the 
parsing function docs not return, they can be rubbed out This works 
only for characters with no modifier bits. 

(:preemptable value) 

Makes all blips read as input by the rubout handler act as preemptive 
commands. If this option is specified, the rubout handler returns 
immediately when it reads a blip. It returns two values: the blip diat was 
read, and value. The parsing ftmetion is not allowed to finish parsing up 
to a delimiter; instead, any buffered input remains in the buffer for the 
next time input is done. In the mean time, the preemptive command 
character can be processed by the command loop. 

While this applies to all blips, the blips which it is probably intended for 
are mouse blips. 

(;command fn args...) 

Makes certain characters preemptive commands. A preemptive command 
returns instantly to the caller of the irubout-handler operation, regardless 
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of the input in the btiftcr. It returns two values: a list (:command char 
numcric-arg) and the keyword :command. The parsing function is not 
allowed to finish parsing up to a delimiter; instead, any buflered input 
remains in die buffer for the next time input is done. In the mean time, 
the preemptive command character can be processed by the command 
loop. 

Hie test for whether a character should be a preemptive ct)mmand is done 
using fn and args just as in :activation. 

(:editing-command (c/wr ^/«^•)...) 

Defines editing commands to be executed by the parsing function itself. 
This is how qsend implements the Control-Meta-Y command. Kach char 
is such a command, and doc says what it docs, (doc is printed out by the 
nibout handler's Help command.) If any of these characters is read by tiie 
nibout handler, it is returned immediately to the parsing function 
regardless of where the editing pointer is in tlic buffer. (Normal inserted 
text is not returned immediately when read unless the editing pointer is at 
the end of the buffer.) 

The parsing function should not regard these characters as part of the 
input. I'here are two reasonable things that the parsing function can do 
when it receives one of flie editing command characters; print some 
output, or force some input 

If it prints output it should invoke the ;refresh-rubout-handler 
operation afterward before the next :tyi. This causes the rubout handler to 
redisplay so that the input being edited appears after the output that was 
done. 

If the parsing function forces input the input is read by the rubout 
handler. This can be used to modify the buffered input qsend’s 
Control-Meta-Y command works by forcing the yanked text as input 
There is no way to act directly on the buffered input because different 
implementations of the rubout handler store it in different ways. 

(.promptjunction) 

{-.reprompt Junction) . v 

When it is time for the user to be prompted, function is called with two 

arguments. The first is a stream it may print on; the second is the 
character which caused the need for prompting, e.g. #\clear-input or 
#\clear-screen, or nil if the rubout handler was just entered. 

The difference between :prompt and :reprompt is that the latter does not 
call the prompt function when the rubout handler is first entered, but 
only when the input is redisplayed (e.g. after a screen clear). If both 
options are specified then :reprompt overrides iprompt except when the 
rubout handler is first entered. 
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fuiiclion may also be a string. I'licn it is simply printed.' 

if the riibout handler is exited with an empty buffer due to tlie :full- 
rubout option, whatever prompt was printed is erased. 

(:initial-input s7r///g) 

Pretends that the user typed string. When die rubout handler is entered, 
string is typed out. I'he user can input more cliaracters or nib out 
characters from it. 

(anitial-input-index/Wejf) 

I’ositions tlie editing pointer initially index characters into the initial input 
string. Used only in company with with :initial-input. 

(:no-input-savet) 

Don't save diis batch of input in the input history when it is done. For 
example, yes-or-no-p specifies this option. 

(morecursive t) 

If this invocation of the rubout handler is within another one, the options 
specified in the previous call should be completely ignored during this one. 
Normally, individual options specified this time override the previous 
settings for tlie same options, but any of tlie previous options not 
individually, overridden are still in effect. 

Rubout handlers handle the condition sys:parse-error if it is signaled by the parsing 
function. The handling consists of printing the error message, waiting for the user to rub out, 
erasing the error message, and parsing the input again. All errors signaled by a parsing function 
that signify that the user's input was syntactically invalid should have this condition name. For 
example, the errors read signals have condition name sys:parse-error since it is is a consequence 
of sys:read-error. 

sys: parse-error (error) Condition 

The condition name for syntax errors in input being parsed. 

The compiler handles sys:parse-error by proceeding with proceed-type :no-action. All 
signalers of sys:parse-error should offer this proceed type, and respond to its use by continuing 
to parse, ignoring the invalid input 

sys;parse-ferror format-string &rcst args 

Signals a sys:parse-error error, using format-string and args to print the error message. 
The proceed-type :no-action is provided, and if a handler uses it, this function returns 
nil. 
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23. Expression Input and Output 

People cannot deal directly with Lisp objects, because the objects live inside tlic machine. In 
order to let us get at and Utlk about Lisp objects, Lisp provides a representation of objects in the 
form of printed text; tliis is called tlic primed represematmi. 'lids is what you have been seeing 
in the examples throughout this manual. Functions such as print, print, and princ take a Lisp 
object and send tlic characters of its printed representation to a stream. 'Lhese functions (and the 
internal functions tlicy call) arc known as tlic printer, 'flic read function takes characters from a 
stream, interprets tlicm as a printed representation of a Lisp object, builds a corresponding object, 
and returns it. It and related functions arc known as the reader. (Streams arc explained in 
section 22.3, page 459.) 

For the rest of tlic chapter, the phrase ‘printed representation’ is abbreviated as ‘p.r.’ 

23.1 What the Printer Produces 

The printed representation of an object depends on its type. In this section, we consider each 
type of object and explain how it is printed. There are several variables which you can set before 
calling the printer to control how certain kinds of objects print. ITiey arc mentioned where 
relevant in this section and summarized in the following section, but one of them is so important 
it must be described now. 'I'his is the escaping feature, controlled by the value of ’print- 
escape*. 

Escaping means printing extra syntactical delimiters and escape characters when necessary to 
avoid ambiguity. Without escaping, a symbol is printed by printing the contents of its name; 
therefore, the symbol whose name consists of the three characters 1, . and 5 prints just like the 
floating point number 1.5. Escaping causes the symbol to print as |1.5| to differentiate the two. | 
is a kind of escape character; see page 516 for more information on escape characters and what 
they mean syntactically. 

Escaping also involves printing package prefixes for symbols, printing double-quotes or suitable 
delimiters around the contents of strings, pathnames, host names, editor buffers, condition 
objects, and many other things. For example, without escaping, the pathname SYS: SYS; 
QCP1 LISP prints as exactly those characters. The string with those contents prints 
indistinguishably. With escaping, the pathname prints as 

#cFS:LOGICAL-PATHNAME "SYS: SYS; QCPl LISP"d 
and the string prints as "SYS: SYS; QCPl LISP". 

The non-escaped version is nicer looking in general, but if you give it to read it won’t do 
the right tiling, ’fhc escaped version is carefully set up so that read will be able to read it in. 
Printing with escaping is useful in writing expressions into files. Printing without escaping is 
useful when constructing messages for the user. However, when the purpose of a message printed 
for the user is to mention an object, the object should be printed with escaping: 
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Your output is in the file SYS: SYS; QCPl QFASL. 
vs . 

Expected pathname properties missing from 
#cFS:LOGICAL-PATHNAME "SYS: SYS; QCPl LISP"d. 

Tlic printed representation of an object also may depend on whether Common l.isp syntax is 
in use. Common l.isp syntax and traditional /ctalisp syntax arc incompatible in st)mc aspects of 
their specifications. In order to print objects so that tlicy can be read back in, tlic printer needs 
to know which syntax rules the reader will use. This decision is based on die current rcadtablc: 
the value of *readtable* at tlic time printing is done. 

Now we describe how each type of object is sUindardly printed. 

Integers: 

For an integer (a fixnum or a bignum): the printed representation consists of 

* a possible radix prefix 

* a minus sign, if the number is negative 

* the representation of the number’s absolute value 

* a possible radix suffix. 

The radix used for printing the number’s absolute value is found as the value of ‘print- 
base*. ’fhis should be cither a positive fixnum or a symbol with an si:princ-function property. 
In the former case, the number is simply printed in that radix. In the latter case, the property is 
called as a function with two arguments, minus the absolute value of the number, and the stream 
to print on. TTie property is responsible for all printing. If the value of ‘print-base* is 
unsuitable, an error is signaled. 

A radix prefix or suffix is used if either ‘nopoint is nil and the radix used is ten, or if 
‘nopoint is non-nil and ‘print-radix* is non-nil. For radix ten, a period is used as the suffix. 
For any other radix, a prefix of the form if radix r is used. A radix prefix or suffix is useful to 
make sure that read parses the number using the same radix used to print it, or for reminding 
the user how to interpret the number. 

Ratios: 

The printed representation of a ratio consists of 

* a possible radix prefix 

* a minus sign, if the number is negative 

* the numerator 

* a ratio delimiter 

* the denominator 
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If Common l.isp synttix is in use, the ratio delimiter is a slash (/). If traditional syntttx is in 
use, backslash (\) is used. Ihc numerator and denominator arc printed iiccording to ‘print- 
base*. 

The condition for printing a radix prefix is the same as for integers, but a prefix #10r is 
used to indicate radix ten, ratlicr than a pcritxi suffix. 

Kloating Point Numbers: 

* a minus sign, if the number is negative 

* one or more decimal digits 

* a decimal point 

* one (ir more decimal digits 

* an exponent, if die number is small enough or large enough to require one. 'ITnc exponent, 
if present, consists of 

* a delimiter, the letter e, s or f 

* a minus sign, if the exponent is negative 
one to three decimal digits 

I’he number of digits printed is just enough to represent all the significant mantissa bits the 
number has. Feeding the p.r. of a float back to the reader is always supposed to produce an 
equal float. Floats arc always printed in decimal; they are not affected by escaping or by * print- 
base*, and there are never any radix prefixes or suffixes. 

The Lisp Machine supports two floating point number formats. At any time, one of them is 
the default; tliis is controlled by the value of *read-default-float-format*. When a floating 
point number whose format is ml currently the default is printed, it must be printed with an 
exponent so that the exponent delimiter can specify the format. The exponent is introduced in 
this case by f or s to specify the format To the reader, f specifies single-float format and s 
specifies short-float format 

A floating point number of the default format is printed with no exponent if this looks nice; 
namely, if this does not require too many extra zeros to be printed before or after the decimal 
point. Otherwise, an exponent is printed and is delimited widi e. To the reader, e means ‘use 
the default format’. 

Normally the default float format is single-float. Therefore, the printer may print full size 
floats without exponents or with e exponents, but short floats are always printed with exponents 
introduced by s so as to tell the reader to make a short float 
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Complex Numbers; 

I he traditional printed representation of a complex number consists of 

* tltc real part 

* a plus sign, if the imaginary part is positive 

* the imaginary part 

* the letter i, printed in lower ease 

If the imaginary part is negative, tlie + is omitted since the initial - of tlic imaginary part 
serves to separate it from the real part. 

In Common Lisp syntax, a complex number is printed as #C{realpart ima^ar{)\ for 
example, #C(5 3). Common Lisp inexplicably does not allow the more natural 5 + 3i syntax. 

The real and unaginary parts are printed individually according to the specifications above. 

Symbols: 

If escaping is off, the p.r. is simply tlie successive characters of the print-name of the symbol. 
If escaping is on, two changes must be made. First, the symbol might require a package prefix 
in order that read work correctly, assuming tliat tlie package into which read will read the 
symbol is the one in which it is being printed. See the chapter on packages (chapter 27, page 
636) for an explanation of the package name prefix. If the symbol is one which would have 
another symbol substituted for it if printed normally and read back, such as the symbol member 
printed using Common Lisp syntax which would be replaced with cli:member if read in thus, it 
is printed with a package prefix (e.g., globahmember) to make it read in properly. See page 519 
for more information on this. 

If the symbol is unintemed, #: is printed instead of a package prefix, provided *print- 
gensym* is non-nil. 

Secondly, if the p.r. would not read in as a symbol at all (that is, if the print-name looks like 
a number, or contains special characters), then escape characters are added so as to suppress the 
other reading. Two kinds of escape characters may be used: single-character escapes and multiple 
escapes. A single-character escape can be used in front of a character to overrule its special 
syntactic meaning. Multiple escapes are used in pairs, and all the characters between the pair 
have their special syntactic meanings suppressed except single-character escapes. If the symbol 
name contains escape characters, they are escaped with single-character escapes. If the symbol 
name contains anything else problematical, a pair of multiple escape characters are printed around 
it. 

The single-character and multiple escape characters are determined by the current readtable. 
Standardly the multiple escape character is vertical bar (|), in both traditional and Common Lisp 
syntax. The single-character escape character is slash (/) in traditional syntax and backslash (\) in 
Common Lisp syntax. 
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FOO ; typical symbol, name composed of upper case letters 

A/|B ;symbol with a vertical bar in its name 

ISymbol with lower case and spaces in its name| 

|0ne containing slash (//) and vertical bar (/j) also] 

Hxcept when multiple escape characters arc printed, any upper case letters in the symbors 
name may be printed as lower case, according to the value of die variable ’print-case*. Iliis is 
true whether escaping is enabled or not. See the next section for details. 

Conses: 

'I'hc p.r. for conses tends to favor lisis. It starts with an open-parenthesis. Then the car of 
the cons is printed and the edr of the cons is examined. If it is nil, a close-parenthesis is printed. 
If it is anything else but a cons, space dot space followed by that object is printed. If it is a 
cons, we print a space and start all over (from the point after we printed tlic open-parenthesis) 
using this new cons. Thus, a list is printed as an open-parenthesis, the p.r.’s of its elements 
separated by spaces, and a close-parenthesis. Ihis is how die printer produces representations 
such as (a b (foo bar) c) in preference to synonymous forms such as (a . (b . ((foo . (bar . 
nil)) . (c . nil)))). 

The following additional feature is provided for the p.r. of conses: as a list is printed, print 
maintains the length of the list so far and the depth of recursion of printing lists. If the length 
exceeds the value of the variable ’print-length*, print terminates the printed representation of 
the list with an ellipsis (three periods) and a close-parenthesis. If the depth of recursion exceeds 
the value of the variable ’print-level*, then the character # is printed instead of the list. These 
two features allow a kind of abbreviated printing that is more concise and suppresses detail. Of 
course, neither the ellipsis nor the # can be interpreted by read, since die relevant information is 
lost. In Common Lisp read syntax, either one causes read to signal an error. 

If ’print-pretty* is non-nil, conses are given to the grinder to print 

If ’print-circle* is non-nil, a check is made for cars or edrs that are circular or shared 
structure, and any object (except for an interned symbol) already mentioned is replaced by a #«# 
label reference. See page 524 for more information on them. 

(let ((•print-circle* t)) 

(print (circular-list 3 4))) 

prints 

#1= (3 4 . #1#) 


PS:<I ..M AN>RDPin'.TKXT.29 


8-JUN-84 



511 


l isp Machine Manual 


Wliai iho Printer Produces 


Character Objects: 

When escaping is off, a character object is printed by printing the character itself, with no 
delimiters. 

In Common l.isp syntax, a character object is printed with escaping as itf(ml\character-or- 

name, font is die character’s font number, in decimal, or is omitted if zero, characict-or-name 

begins with prefixes for any modifier bits (control, mcUi, etc.) present in tlte character, each 

followed by a hyphen. 'Phen comes a representation of the character sans font and modifier bits. 

If tills reduced character is a gniphic character, it represents itself. Otherwise, it certainly has a 
standard name; the name is used. If a graphic characters has special syntactic properties (such as 
whitespace, paretheses, and macro characters) and modifier bit prefixes have been printed tlien a 
single-character escape character is printed before it. 

In traditional syntax, tlic p.r. is the similar except tliat the \ is replaced by */. 


Strings: 

If escaping is off, the p.r. is simply the successive characters of tlic string. If escaping is on, 
double-quote characters (‘"') are printed surrounding the contents, and any single-character escape 
characters or double-quotes inside the contents are preceded by single-character escapes. If the 
string contains a Return character followed by an open parenthesis, a single-character escape is 
printed before the open parenthesis. Examples: 

"Foo" 

"/"Foo/", he said." 


Named Structures: 

If the named structure type symbol has a named-structure-invoke property, the property is 
called as a function with four arguments: the symbol :print-self, the named structure itself, the 
stream to print on, and the current depth of list structure (see below). It is tliis function’s 
responsibility to output a suitable printed representation to the stream. Tliis allows a user to 
define his own p.r. for his named structures: more information can be found in the named 
structure section (see page 390). Typically the printed representation used starts with either #< if 
it is not supposed to be readable or #c (see page 527) if it is supposed to be readable. 

If the named structure symbol does not have a named-structure-invoke property, the 
printed-representation depends on whether escaping is in use. If it is, syntax is used: 

#s ( named-structure-symbol 
component value 
component value 

Named structure component values are checked for circular or shared structure if ‘print-circle* is 
non-nil. 

If escaping is off, the p.r, is like that used for miscellaneous data-types: #<, the named 
structure symbol, the numerical address of the structure, and >. 
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Other Arrays; 

If *print-array* is non-nil, tlie array is printed in a way which shows the elements of the 
array. Bit vectors use #* syntax, other vectors use #(,..) syntax, and arrays of rank other than 
()nc use #;/a(...) syntax. I'hc printed representation does not indicate the array type (that is, 

what elemeiiLs it is allowed to contain). If the printed representiition is read in, a general array 

(array type art-q) is always created. See page 52.^ for more infonnation on tliese syntaxes. 
Kxamples; 

(vector 1 2 5) => #(1 2 5) 

(make-array ’(2 4) :initial-element t) => #2a((t t t t) (t t t t)) 

Vector and array groupings count like list groupings in maintaining the depth value that is 

compared with ‘print-level* for cutting olf things tliat get too deep. More titan ‘print-length* 
elements in a given vector or array grouping level are cut off with an ellipsis just like a list tliat is 
so long. 

Array elements are checked for circular or shared structure if ‘print-circle* is non-nil. 

If ‘print-array* is nil, the p.r. starts with #<. 'I’hen the art- symbol for the array type is 
printed. Next die dimensions of die array are printed, separated by hyphens, 'litis is followed by 
a space, the machine address of the array, and a >, as in # <ART-COMPLEX-FLOAT-3-6 
34030451>. 

Instances and Entities: 

If the object says it can handle the :print-self message, that message is sent with three 
arguments: the stream to print to, the current depth of list structure (sec below), and whether 
escaping is enabled. ITie object should print a suitable p,r, on the stream. See chapter 21, page 
401 for documentation on instances. Most such objects print like “any other data type” below, 
except with addidonal information such as a name. Some objects print only their name when 
escaping is not in effect (when prine'ed). Some objects, including pathnames, use a printed 
representation that begins with #c, ends with d, and contains sufficient information for the reader 
to reconstruct an equivalent object. See page 527. If the object cannot handle :print-self, it is 
printed like “any other data type”. 

Any Other Data Type: 

ITie printed representation starts with #< and ends with >. This sort of printed representation 
cannot be read back in. The #< is followed by the dtp- symbol for this datatype, a space, and 
the octal machine address of the object. 'The object’s name, if one can be determined, often 
appears before the address. If this style of printed representation is being used for a named 
structure or instance, other interesting information may appear as well. Finally a greater-than sign 
(>) is printed in octal. Examples: 

#’equal => #<DTP-U-ENTRY EQUAL 410> 

(value-cell-location nil) => #<DTP-L0CATIVE 1> 

Including the machine address in the p.r. makes it possible to tell two objects of this kind 
apart without explicitly calling eq on them. 'This can be very useful during debugging. It is 
important to know that if garbage collection is turned on, objects will oaasionally be moved, and 
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therefore tltcir iK-tal machine addresses will be changed, k is best to shut off garbage collection 
temporarily when depending on these numbers. 

Printed representations tliat start with '#<' can never be read back. This can be a problem if, 
for example, you are printing a structure into a file with the intent of reading it in later. ITic 
following feature allows you to make sure that what you are printing may indeed be read with tlie 
reader. 

si :pr1nt-readab1y Variable 

When si:print-readably is bound to t, the printer signals an error if there is an attempt 
to print an object that cannot be interpreted by read. When the printer sends a :print- 
self or a rprint message, it assumes tliat tliis error checking is done for it. 'Ihus it is 
possible for these messages not to signal an error, if they see fit. 

si:printing-random-object (object stream . keywords) &.hoi\y body Macro 

fhe vast majority of objects that define :print-self messages have much in common. ITiis 
macro is provided for convenience so that users do not have to write out that repetitious 
code. It is also tlic preferred interface to si:print-readably. With no keywords, 
si:printing-random-object checks die value of siiprint-readably and signals an error if it 
is not nil. It then prints a number sign and a Icss-lhan sign, evaluates die forms in body, 
then prints a space, the octal machine address of the object and a greater-than sign. A 
typical use of this macro might look like: 

(sirprinting-random-object (ship stream :typep) 

(tyo #\space stream) 

(prinl (ship-name ship) stream)) 

This might print #<ship "ralph" 23655126>. 

The following keywords may be used to modify the behaviour of si:printing-random-object: 

:no-pointer This suppresses printing of the octal address of the object. 

dype This prints the result of (type-of object) after the less-than sign. In the example 

above, this option could have been used instead of the first two forms in the 
body. 

sys:pr1nt-not-readab1e (error) ‘ Condition 

This condition is signaled by si:print-readably when the object cannot be printed 
readably. 

The condition instance supports the operation :obiect, which returns the object that was 
being printed. 

If you want to control the printed representation of some object, usually the right way to do 
it is to make the object an array that is a named structure (see page 390), or an instance of a 
flavor (sec chapter 21, page 401). However, occasionally it is desirable to get control over all 
printing of objects, in order to change, in some way, how they are printed. If you need to do 
this, tlie best way to proceed is to customize the behavior of si: print-object (see page 543), 
which is the main internal function of the printer. All of the printing functions, such as print 
and princ, as well as format, go through this function. ITie way to customize it is by using the 
“advice" facility (sec section 30.10, page 742). 
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23.2 Options that Control PrlntM^ 

Several special variables arc defined by Uic system for the user to set or bind before calling 
print or other printing functions. Their values, as set up by tlic user, control how various kinds 
of objects arc printed. 


•print-escape* yariable ^ 

1-scaping is done if this variable is non-nil. See the previous section for a description of 
the many effects of escaping. Most of the output functions bind this variable to t or to 
nil, so you rarely use the \ariable itself. 


•print-base* 

base 

'I'he radix to use for printing integers and ratios, riic value must 
from 2 to 36 or a symbol with a valid shprinc-function property, 
;english. 


Variable 

Variable 

be eitlier an integer 
such as :roman or 


llie default value of *print-base* is ten. In input from files, the Base attribute (see 
section 25.5, page 594) controls the value of ‘print-base* (and of ‘read-base*). 


The synonym base is from Maclisp. 

.prmt-rsdlx* . , . ^ 

If non-nil, integers and ratios are output with a prefix or suffix indicating the radix used 

to print them. For integers and radix ten. a period is printed as a suffix. Otherwise, a 
prefix such as or is printed. The default value of ‘print-radix* is nil. 

•nopolnt .... 

If the value of ‘nopoint is nil, a trailing decimal point is printed when a nxnum is 

printed out in base 10. lliis allows the numbers to be read back in correctly even if 
‘read-base* is not 10 at the time of reading. The default value of ‘nopoint is t. 
‘nopoint has no effect if ‘print-radix* is non-nil. 

‘nopoint exists for Maclisp compatibility. But to get truly compatible behavior, you must 
set ‘nopoint to nil (dnd, by default, base and ibase to eight). 

•pr1nt-c1rcU* _ , _ 

If non-nil, the printer recognizes circular and shared structure and pnnts it using #n- 

labels so that it has a finite printed representation (which can be read back in). The 
default is nil, since t makes printing slower. See page 524 for information on the 
construct 


•print-pretty* 


Variable 


If non-nil, the printer actually calls grind-top-level so that it prints extra whitespace for 
the sake of formatting. The default is nil. 
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•pr1nt-gensyra* Variable 

If non-nil. unintcrncd symbols arc printed with the prefix to mark tlicm as such (but 
only when ‘print-escape* is non-nil). I'he prefix causes the reader to construct a similar 
unintcrncd symbol when the expression is read. If nil, no prefix is used for unintcrncd 
symbols. 'I'he default is t. 

*pr1nt-arpay* Variable 

If non-nil. non-string arrays arc printed using the #(...), #* or syntax so that you 

can see their contents (and so that tlicy can be read back in). If nil, such arrays arc 
printed using #<...> syntax and do not show their contents. The default is nil. 'Hie 
printing of strings is not alTcctcd by tliis variable. 

*pp1nt-case* Variable 

Controls the ease used for printing upper-ease letters in the names of symbols. Its value 
should be :upcase, :downcase or capitalize. These mean, respectively, to print those 
letters as upper ease, to print tliem as lower case, or to capitalize each word (see string- 
capitalize, page 213). Any lower ease letters in the symbol name arc printed as lower 
case and escaped suitably: this flag docs not affect them. Note that the ease used for 
printing the upper case letters has no effect on reading the symbols back in, since they 
arc case-converted by read. Any upper ease letters tliat happen to be escaped arc always 
printed in upper case. 


idowncase ;cap1ta1ize)) 


{dolist (*print-case* ’(lupcase 
(prinl-then-space ’foo) 

(prinl-then-space ’|Foo|)) 
prints FCX) iFool foo |Foo| Foo |Foo| . 

*pp1nt-l0vel* Variable 

prlnlevel Variable 

•print-level* can be set to the maximum number of nested lists that can be printed 
before the printer gives up and just prints a # instead of a list element If it is nil, 
which it is initially, any number of nested lists can be printed. Otherwise, the value of 
•print-level* must be a fixnum. Example: 

(let ({♦print-level* 2)) 

(prinl ’(a (b (c (d e)))))) 
prints (a (b #)). 

The synonym prinlevel is from Maclisp. 


•print-length* 
prinlength 


Variable 
Variable 

•print-length* can be set to the maximum number of elements of a list that can be 
printed before the printer gives up and prints an ellipsis (three periods). If it is nil, 
which it is initially, any length list may be printed. Example: 

(let ({*print-length* 3)) 

(prinl ’((a b c d) #(e f g h) (i j k 1) (m n o p)))) 
prints ((a b c ...) #(e f g ...) (i j k ...) ...). 
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The synonym prinlength is from Maclisp. 

23.3 Whal I'he Reader Accepts 

'fhe purpose of the reader is to accept characters, interpret them as tlie p.r. of a I asp object, 
and create and return such an object, fhe reader cannot accept everything lliat the printer 
produces; for example, the p.r.'s of compiled c(xle objects, closures, stack groups, etc., cannot be 
read in. However, it has many features tliat are not seen in the printer at all. such as more 
flexibility, comments, and convenient abbreviations for frcqucntly-used unwieldy constructs. 

'I'his section shows what kind of p.r.'s the reader understands, and explains the rcadtable, 
reader macros, and various features provided by read. 

The syntax specified for Common I.isp is incompatible with the traditional Zctalisp syntax, 
'fhereforc, the Lisp Machine supports both traditional and Common Lisp syntax, but read must 
be told in advance which one to use. Tliis is controlled by the choice of readable (see section 
23.6, page 535). When reading input from a file, the Lisp system chooses tlie syntax according to 
the file’s attribute list; Common Lisp syntax is used if tlie Common Lisp attribute is present (see 
section 25.5, page 594). 

I'hc main difference between traditional and Common Lisp syntax is that traditionally the 
single-character escape is slash (/), whereas in Common Lisp syntax it is backslash (\). Thus, the 
division function which in traditional syntax is written // is written just / in Common Lisp 
syntax. The other differences arc obscure and arc mentioned below where they occur. 

In general, the reader operates by recognizing tokens in the input stream. Tokens can be self- 
delimiting or can be separated by delimiters such as whitespace. A token is the p.r. of an atomic 
object such as a symbol or number, or a special character such as a parenthesis. The reader reads 
one or more tokens until the complete p.r. of an object has been seen, then constructs and 
returns that object 

Escape characters can be used to suppress the special syntactic significance of any character, 
including Space, ( or ". There are two kinds of escape character: the single-character escape 
(/ in traditional syntax, \ in Common Lisp syntax) suppresses the significance of the immediately 
following character; multiple escapes (vertical bar, |) are used in pairs, and suppress the special 
significance of all the characters except escapes between the pair, taping a character causes it to 
be treated as a token constituent and causes the token containing it to be read as a symbol. For 
example, (12 5 x) represents a list of three elements, two of which are integers, but (712 5/ x) 
or (|15l |5 X|) represents a list of two elements, both symbols. Escaping also prevents conversion 
of letters to upper case, so that lx| is the symbol whose print name contains a lower-case x. 

The circle-cross (») character an octal escape character which may be useful for including 
weird characters in the input. The next three characters are read and interpreted as an octal 
number, and the character whose code is that number replaces the circlc-cross and the digits in 
the input stream. This character is always treated as a token constituent and forces the token to 
be read as a symbol. ® is allowed in both traditional and Common Lisp syntax, but it is not 
valid Common Lisp. 
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Integers: 

The reader understands the p.r.’s of integers in a way more general than is employed by the 
printer. Here is a complete description of the format for integers. 

Let a simple inleger be a string of digits, optionally preceded by a plus sign or a minus sign, 
and optionally followed by a trailing decimal point. A simple integer is intciprctcd, by read as an 
integer. If the trailing decimal point is present, the digits arc interpreted in decimal radix; 
otherwise, they are considered as a number whose radix is the value of the variable *read-base*. 

•read-base* Variable 

•I base Variable 

llic value of ibase or ’read-base* is an integer between 2 and 36 tltat is tlie radix in 
whicli integeis and ratios are read, "fhe initial value of is ten. For input from files or 
editor buffers, the Base attribute specifics the value to be used (sec section 25.5, page 
594); if it is not given, the ambient value is used. 

Tlic synonym ibase is from Maclisp. 

If the input radix is greater than ten, letters starting with a arc used as additional “digits” 
with values ten and above. For example, in radix 16, the letters a through f are digits with 
values ten tlirough 15. Alphabetic case is not significant. 'I'hcsc additional digits can be used 
wherever a simple integer is expected and are parsed using the current input radix. For example, 
if *read-base* is 16 tlicn ff is recognized as an integer (255 decimal). So is 10e5, which is a 
float when *read-base* is ten. 

Traditional syntax also permits a simple integer, followed by an underscore (_) or a circumflex 
followed by another simple integer. ITie two simple integers arc interpreted in the usual 
way; the character in between indicates an operation that is then performed on the two integers. 
ITie underscore indicates a binary “left shift”; that is, the integer to its left is doubled the 
number of times indicated by the integer to its right. The circumflex multiplies the integer to its 
left by ‘read-base* the number of times indicated by the integer to its right. (The second 
simple integer is not allowed to have a leading minus sign.) Examples: 3_2 means 12 and 645''3 
means 645000. 

Here are some examples of valid representations of integers to be given to read: 

4 

23456. 

-546 

+45^+6 ;mcans 45000000 

2_11 ;4096 

72361356126536125376512375126535123712635 

-123456789. 

105_1000 ;(ash 105 1000) has this value. 

105_1000. 
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Floating Point Numbers: 




Floats can be written with or without exponent. The syntax for a float without exponent is an 
optional plus or minus sign, optionally some digits, a decimal point, and one or more digits. A 
float with exponent consists of a simple integer or a float without exponent, followed by an 
exponent delimiter (a letter) and a simple integer (the exponent itself) which is the power of ten 
by which the number is to be scaled. The exponent may not have a trailing decimal point. Both 
the mantissa and the exponent arc always interpreted in base ten, regardless of lltc value of 
*read-base*. 

Only certain letters are allowed for delimiting the exponent: e. s, f, d and I. 'Hie case of 
the letter is not significant, s specifics that the number should be a short float; f, that it should 
be a full'Sizc float, d or 1 arc equivalent to f; Common l.isp defines them to mean “double float’ 
or “long float', but the l.isp Machine docs not support anything longer than a full-size float, so it 
regards d and 1 as synonymous with f. e tells the reader to use the current default format, 
whatever it may be, as specified by the value of *read-default-float-format*. 

•pead-default-fl oat-format* Variable 

'I'hc value is tlic type for read to produce by default for floats whose precise type is not 
specified by the syntax. The value should be either globahsmall-float or globahsingle- 
float, these being the only distinct floating formats that the Lisp Machine has. ITie 
default is single-float, to make full-size floats. 

Here are some examples of printed-representations that always read as full-size floats: 

6,03f23 lF-9 l.f3 3d6 


Here are some examples of printed-representations that always read as short floats: 


OsO 

1.5s9 

-42S3 l.s6 

These read as floats^ or as 

a short floats according to ’read-default-float-format*: 

0.0 

1.5 

14.0 0.01 

.707 

-.3 

+3.14159 6.03e23 

lE-9 

l.e3 


Rationals: 




The syntax for a rational is an integer, a ratio delimiter, and another integer. The integers 
may not include the and _ scaling characters or decimal points, and only the first one may 
have a sign. The ratio delimiter is backslash (\) in traditional syntax, slash (/) in Common Lisp 
syntax. Here are examples: 

1\2 -100000000000000X3 80X10 traditional 

1/2 -100000000000000/3 80/10 Common IJsp 

Recall that rationals include the integers; 80X10 as input to the reader is equivalent to 8. 
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CiHnplex Numbers: 

'Hie traditional syntax for a complex number is a number (for the real part), a sign (+ or -), 
an unsigned number (for the imaginary part), and the letter i. The real and imaginary parts can 
be any type of number, but they arc converted to be of the same type (both floating of the same 
format, or both rational). For example: 
l-3\4i 

1.2s0+3.45s8i 

The Common Lisp syntax for a complex number is #c{real imag), where real is the real 
part and imag is the imaginary part. I'liis construction is allowed in traditional syntax too. 

#c{l -3/4) 

#c(1.2s0 3.45s8) 

Symbols: 

A string of letters, numbers, and characters without special syntactic meaning is recognized by 
tlic reader as a symbol, provided it cannot be interpreted as a number. Alphabetic case is 
ignored in symbols; lower-case letters are translated to upper-ease unless escaped. When the 
reader sees the p.r. of a symbol, it interns it on a package (see chapter 27, page 636, for an 
explanation of interning and the package system). Symbols may start with digits; you could even 
have one named -345t; read accepts this as a symbol without complaint. If you want to put 
strange characters (such as lower-case letters, parentheses, or reader macro characters) inside the 
name of a symbol, they must be escaped. If the symbol’s name would look like a number, at 
least one character in the name must be escaped, but it matters not which one. 

Examples of symbols: 
foo 

bar/(baz/) ; traditional 

bar\(ba 2 \) ; Common Lisp 

34w23 

|Frob Sale I and F|rob |S|ale| are equivalent 

|a/|b| ; traditional 

I a\ I b I ; Common Lisp 

In Common Lisp syntax, a symbol composed only of two or more periods is not allowed 
unless escaping is used. 

The reader can be directed to perform substitutions on the symbols it reads. Symbol 
substitutions are used to implement the incompatible Common Lisp definitions of various system 
functions. Reading of Common Lisp code is done with substitutions that replace subst with 
cli:subst, member with cli:member, and so on. This is why, when a Common Lisp program 
uses tlie function member, it gets the standard Common Lisp member function rather than the 
traditional one. 'Ihis is why we say that cli:member is “the Common Lisp version of member”. 
While cli:member can be referred to from any program in just that way, it exists primarily to be 
referred to from a Common Lisp program which says simply member. 
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Symbol substitutions do not apply U) symbols written with package prefixes, so one can use a 
package prefix to force a reference to a symbol that is normally substituted for, such as using 
globahmember in a Common Lisp program. 

Strings: 

Strings arc written with double-quote characters (") before and after tlic string contents, 'fo 
include a double-quote character or single-character escape character in tlic contents, write an 
extra single-character escape character in front of it. 

Hxamples of strings: 

"This is a typical string." 

"That is a /"cons cell/"." ;; traditional 

"That is a \"cons cell\"." ;; Common Lisp 

"Strings are often used for I//0." ;; traditional 

"Strings are often used for I/O." ;;Common Lisp 

"Here comes one backslash: \\" ;; Common Lisp 


Conses: 

When read sees an open-parenthesis, it knows that the p.r. of a cons is coming, and calls 
itself recursively to get the elements of the cons or the list that follows. The following are valid 
p.r.’s of conses: 

(foo . bar) 

(foo "bar" 33) 

(foo . ("bar" . (33 . nil))) 

(foo bar . quux) 

The first is a cons, whose car and edr arc both symbols. The second is a list, and the third is 
equivalent to the second (although print would never produce it). The fourth is a dotted list; the 
edr of the last cons cell (the second one) is not nil, but quux. 

The reader always allocates new cons cells to represent parentheses. They are never shared 
with other structure, not even part of the same read. For example, 

(let ((x (read))) 

(eq (car x) (edr x))) 

((ab) . (ab)) ;; data for read 

=> nil 

because each time (a b) is read, a new list is constructed. This contrasts with the case for 

symbols, as very often read returns symbols that it found interned in the package rather than 

creating new symbols itself. Symbols are the only thing that work this way. 

The dot that separates the two elements of a dotted-pair p.r. for a cons is only recognized if 

it is surrounded by delimiters (typically spaces). ITius dot may be freely used within print-names 
of symbols and within numbers. T his is not compatible with Maclisp: in Maclisp (a.b) reads as a 
cons of symbols a and b, whereas in Zetalisp it reads as a list of a symbol a.b. 
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Comments: 

A comment begins with a semicolon (;) and continues to the end of tlic line. Comments arc 
ignored completely by the reader. If the semicolon is escaped or inside a string, it is not 
rccogni/cd as starting a comment; it is part of a symbol or part of die string. 

This is a comment. 

"This is a string; but no comment." 

Another way to write a comment is to start it with #\ and end it with \». This is useful for 
commenting out multiplcTinc segments of code. The two delimiters nest, so that #\ #\ |# 1# 
is a single comment. T his prevents surprising results if you use this construct to comment out 
code which already contains such a comment. 

(cond ((atom x) y) 

#\ 

({foo x) 

(do-it y)) 

I*!* 

(t (hack y))) 

Abbreviations: 

The single-quote character (’) is an abbreviation for a list starting with the symbol quote. 
The following pairs of p.r.'s produce equal lists: 

’a and (quote a) 

’(X (y)) and (quote (x (y))) 

The backquote character (*) and comma are used in a syntax that abbreviates calls to the list 
and vector construction functions. For example, 

'(a .be) 

reads as a list whose meaning as a Lisp form is equivalent to 
(list ’a b ’c) 

See section 18.2.2, page 325 for full details about backquote. 


23.3,1 Sharp-sign Constructs 

Sharp-sign (#) is used to introduce syntax extensions. It is the beginning of a two-character 
sequence whose meaning depends on the second character. Sharp-sign is only recognized with a 
special meaning if it occurs at the beginning of a token. If encountered while a token is in 
progress, it is a symbol constituent. For example, #xff is a sharp-sign construct that interprets 
f f as a hexidecimal number, but l#xf f is just a symbol. 

If the sharp-sign is followed by decimal digits, the digits form a parameter. The first non¬ 
digit determines which sharp-sign construct is actually in use, and the decimal integer parsed from 
the digits is passed to it. For example, means “read in specified radix’; it must actually be 
used with a radix notated in decimal between the # and the r, as in #8r. 
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It is possible for sh;iip-sign construct to have dilTcrcnt meanings in Common Lisp and 
traditional syntax. The only constructs whiclv dilfer arc #\ and #/, 

The function set-dispatch-macro-character (see page 541) can be used to define additional 
sharp sign abbreviations. 

Here arc-the currently-defined sharp sign constructs; 

#/ #/ is used in traditional syntax only to represent the number Uiat is the character civde 

for a character. You can follow the H/ with tlic chanictcr itself, or with the charagter's 
name. I he name is preferable for nonprinting characters, and it is the only way to 
represent characters which have control bits since they cannot go in files. Here arc 
examples of #/: 

#/a #0141 

#/A #ol01 

«/( #o50 

tlic character code for Control-A 
#/c-/a tlie character code for Control-a 

#/c-sh-a die character code for Control-a 

#/c-/A die character code for Control-A 

#/c-/ ( tlic character code for Control-( 

^/return the character code for Return 

#/h-ni-systeni the character code for Hyper-Meta-System 

To represent a printing character, write #/x where x is the character. For example, i^/a 
is equivalent to #o141 but clearer in its intent. To avoid ambiguity, the character 
following X should not be a letter; good style would require diis anyway. 

As in strings, upper and lower-case letters are distinguished after #/. Any character 
works after #/, even those that arc normally special to read, such as parentheses. Thus, 
#/A is equivalent to #o101, and #/{ is equivalent to ^o50. Note that the slash causes 
this construct to be parsed correctly by the editors Emacs and Zmacs. Even non-printing 
characters may be used, but for them it is preferable to use the character’s name. 

To refer to a character by name, write #/ followed by the name. For example, #/return 
reads as the numeric code for the character Return. The defined character names are 
documented below (see section 10.1.6, page 211). In general, the names that arc written 
on the keyboard keys are accepted. In addition, all the nonalphanumcric characters have 
names. I he abbreviations cr for return and sp for space arc accepted, since these 
chaiacters arc used so frequently. ITic page separator character is called page, although 
form and dear-screen are also accepted since die keyboard has one of tJiosc legends on 
the page key. The rules for reading name arc tlie same as those for symbols; dius letters 
arc converted to upper case unle.ss escaped, and the name must be terminated by a 
delimiter such as a space, a carriage return, or a parenthesis. 

When the system types out the name of a special character, it uses the same table that 
#/ uses, tliereforc, any character name tj'ped out is acceptable as input. 
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#/ can also be used to read in the names of characters that have modifier bits (Control, 
Meta, Super and Hyper), rhe syntax looks like /^/control-meta-b to get a ‘B’ character 
with the control and meta bits set. You can use any of the prefix bit names control, 
meta, hyper, and super. They may be in any order, and case is not significant. Prefix 
bit names can be abbreviated as tlie single letters c, m. h and s, and control may be 
spelled Ctrl as it is on die keyboard. The last hyphen may be followed by a single 
character or by any of tlic special character names nonnally recogni/cd by /^/. A single 
character is treated die same way the reader normally treats characters in symbols; if you 
want to use a lower-case character or a special character such as a parenthesis, you must 
precede it by a slash character, l^xamplcs; #/Hyper-Super-A, #/meta-hyper-roman-i, 
#/CTRL-META-/(. 

An obsolete mediod of specifying control bits in a character is to insert the characters «, 
/t, r. w and X between the # and the /. 'Hiose stand for control, meta, control-meta, 
super and hyper, respectively. 'I'his syntax should be converted to the new #\control- 
meta-x syntax described below. 

greek (or front), top, and shift (or sh) are also allowed as prefixes of names. 'ITius, 
#/top-g is equivalent to #/t or ^/uparrow. tf/top-g should be used if you are 
specifying the keyboard commands of a program and die mnemonic significance belongs to 
the ‘G’ rather than to the actual character code; 

#\ In traditional syntax, #\ is a synonym for #/. In the past, #/ had to be used before a 
single character and #\ had to be used in all other cases. Now either one is allowed in 
either case. 

In Common Lisp syntax, #\ produces a character object rather than a fixnum representing 
a character. 

#*/ is the traditional syntax way to produce a character object. It is used just like #/. 

IhuSj Common Lisp #\ is equivalent to traditional syntax #*/. 

if''x is exaedy like #/control-x if the input is being read by Zetalisp; it generates 
Control-x. In Maclisp x is converted to upper case and then exclusive-or’ed with 100 
(octal). Ihus #^x always generates the character returned by tyi if the user holds down 
the control key and types x. (In Maclisp #/control-x sets the bit set by the Control key 
when the TTY is open in fixnum mode.) 

#' #'foo is an abbreviation for (function foo). foo is the p.r. of any object. This 

abbreviation can be remembered by analogy with the ’ macro-character, since the function 
and quote special forms are somewhat analogous. 

#( elements,..) constructs a vector (rank-one array) of type art-q with elements 
elements. The length of the vector is the number of elements written. Thus, #(a 5 
"Foo") reads as a vector containing a symbol, an integer and a string. If a decimal 
integer appears after the #, it specifies the length of the vector, lire last element written 
is replicated to fill the remaining elements. 

#a #na contents signifies an array of rank n, containing contents, contents is passed to 

make-array as the initial-contents argument. It is a list of lists of lists... or vector of 
vectors... as deep as n. The dimensions of the array are specified by the lengths of the 
lists or vectors. The rank is specified explicidy so that the reader can distinguish whether 
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a list or vector in the contents is a sequence of array elements or a single array clement. 
The array type is always art-q. 

Hxamplcs: 

#2a ((X y) (a b) ((uu 3) "VV")) 
produces a 3 by 2 array , (uu 3) is one of the elements. 

#2a ("foo" "bar") 

produces a 2 by 3 array whose elements tire character objects. Recall tliat a string is a 
kind of vector. 

#0a 5 

produces a rank-0 array whose sole clement is 5. 

#*bbb... signifies a bit vector; bbb... arc the bits (characters 1 or 0). A vector of type 
art-1b is created and filled with the specified bits, the first bit specified going in array 
clement 0. The length is however many bits you specify. Alternatively, specify the length 
with a decimal number between the # and the ♦. I'he last 1 or 0 specified is duplicated 
to fill the additional bits. ITius, #8*0101 is the same as #*01011111. 

#s its {type slot value slot value slot value ...) constructs a structure of type type. Any 
structure type defined with defstruct can be used as type provided it has a standard 
constructor taking slot values as keyword arguments. (Sbndard constructors can be 
functions or macros; either kind works for #s.) The slot,names and values appearing in 
the read syntax are passed to the constructor so that they initialize the structure. 
Example: 

(defstruct (foo :named) 
bar 
lose) 

#s (foo :bar 5 :1ose haha) 

produces a foo whose bar component is 5 and whose lose component is haha. 

# Are used to represent circular structure or shared structure. #//= preceding an object 
“labels” that object with the label «, a decimal integer, lliis has no effect on the way 
the object labeled is read, but it makes the label available for use in a #«# construct 
within that object (to create circular structure) or later on (to create shared structure). 
#/j# counts as an object in itself, and reads as tlie object labeled by n. 

For example, #l=(a . #1#) is a way of notating a circular list such as would be 
produced by (circular-list ’a). The list is labeled with label 1, and then its edr is given 
as a reference to label 1. (#l=#:foo #1#) is an example of shared structure. An 
uninterned symbol named foo is used as the first clement of the list, and labeled. The 
second clement of the list is the very same uninterned symbol, by virtue of a reference to 
the label. 

Printing outputs #«= and #«# to represent circular or shared structure when *print-circle 
is non-nil. 

#, Evaluate a form at load time. #, foo evaluates foo (tlie p.r. of a Lisp form) at read time, 
except tliat during filc-to-file compilation it is arranged that foo will be evaluated when the 
QFASL file is loaded. Phis is a way, for example, to include in your code complex list- 
structure constants that cannot be written with quote, Note that the reader docs not put 
quote around the result of tlie evaluation. You must do this yourself if you want it, 
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typically by using Ute ’ macro-character. An example of a case where you do not want 
quote around it is when this bt^t is an element of a constant list 

#. it . foo evaluates foo (the p.r. of a lisp form) at read time, regardless of who is doing the 
reading. 

#' is a construct for repeating an expression with some subexpressions varying. It is an 

abbreviation for writing several siniilar expressions or for the use of mape. Hach 
subexpression that is to be varied is written as a comma ft)llowcd by a list of the tilings 
to substitute. 'I'he expression is expanded at read time into a progn containing the 
individual versions. 

#'(send stream ’ , {:clear-input .-clear-output)) 
expands into 

(progn (send stream :clear-input) 

(send stream :clear-output)) 

Multiple repetitions can be done in parallel by using commas in several subexpressions: 

#'(rename-file .("foo" "bar") ,("ofoo" "obar")) 
expands into 

(progn (rename-file "foo" "ofoo") 

(rename-file "bar" "obar")) 

If you want to do multiple independent repetitions, you must use nested U' constructs. 
Individual commas inside the inner apply to that they vary at maximum speed. 
To specify a subexpression that varies in the outer #', use two commas. 

#'#'(print (* ,(5 7) .,(11. 13.))) 
expands into 

(progn (progn (print (• 5 11.)) (print (♦ 7 11.))) 

(progn (print (♦ 5 13.)) (print (• 7 13.))) 

#0 Ho number reads number in octal regardless of the setting of *read-base*. Actually, any 
expression can be prefixed by #o; it is read with *read-base* bound to 8. 

#b Like #o but reads in binary. 

#x Like #x but reads in radix 16 (hexadecimal). The letters a through f are used as the 
digits beyond 9. 

#r #radixr number reads number in radix radix regardless of the setting of ‘read-base*. As 

with # 0 , any expression can be prefixed by #radixr\ it is read with ‘read-base* bound 
to radix, radix must be a valid decimal integer between 2 and 36. 

For example, #3rl02 is another way of writing 11. and #llr32 is another way of 
writing 35. Bases larger than ten use the letters starting with a as the additional digits. 

#c He (real imag) constructs a complex number with real part real and imaginary part. It is 
equivalent to real + imagi, except that He is allowed in Common Lisp syntax and the 
other is not. 

# + This abbreviation provides a read-time conditiOnalization facility. It is used as H+feature 
form. If feature is a symbol, then this is read as form if feature is present in the list 
‘features* (see page 803). Otherwise, the construct is regarded as whitespace. 
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Alternately, feature nitty be ;t boolean expression composed of and, or, and not operators 
and symbols representing itehis dial may appear on ’features*. I hits, #+(or lispm 
amber) causes die following object to be seen if cidicr of the features lispm or amber is 
present. 

For example, #+lispm fonn makes form count if being read by Zetalisp, and is dius 
equivalent to #q form. Similarly, #+maclisp form is equivalent to #m fimn. #+(or lispm 
nil) form makes form count on either Zetalisp or in NIK. 

Here is a list of features with standard meanings; 

lliis feature is present on any Lisp machine (no matter what version of 
hardware or software). 

This feature is present in Maclisp. 

'lliis feature is present in NIL (New Implementation of Usp). 

This feature is present in the MIT Lisp machine system, which is what 
this manual is about. 

'lliis feature is present in the Symbolics version of die Lisp machine 
system. May you be spared die dishonor of using it. 


lispm 

maclisp 

nil 

mit 

symbolics 


#+, and die other read-time conditionalization constructs that follow, discard the following 
expression by reading it with ’read-suppress* bound to t if the specified condition is 
false. 

#- #-/ea/wre/omMS equivalent to #+(not/ra/Mre)/on«. 

#q #q foo reads as foo if die input is being read by Zetalisp, otherwise it reads as nothing 
(whitespace). 'lliis is considered obsolete; use #+lispm instead. 

#m foo reads as foo if the input is being read into Maclisp, otherwise it reads as nothing 
(whitespace), 'lliis is considered obsolete; use #+maclisp instead. 

#n #n foo reads as foo if the input is being read into NIL or compiled to run in NIL, 
otherwise it reads as nothing (white space), 'fhis is considered obsolete; use #+nil instead. 

#0 introduces an expression in infix notation. ❖ should be used to terminate it. Lhe text 

in between describes a Lisp object such as a symbol, number or list but using a 
nonstandard, infix-oriented syntax. For example, 

:y+car(al[1,j])❖ 
is equivalent to 

(setq X {-*■ y (car (aref al i j)))) 


It is not striedy true diat the Lisp object produced in this way has to be an expression. 
Since the conversion is done at read time, you can use a list expressed this way for any 
purpose. But the infix syntax is designed to be used for expressions. 


For full details, refer to the file SYS: 101; INFIX LISP. 

#< This is not legal reader syntax. It is used in die p.r. of objects that cannot be read back 
in. Attempting to read a #< signals an error. 
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This is used in the p.r. of miscellaneous objects (usually named structures or instances) 
Uiat can be read back in. ttc should be followed by a typename and any other data 
needed to construct an object, terminated with a d. For example, a patlmamc might 
print as 

#cFS: ITS-PATHNAME "AI: RMS; TEST 5"d 
The typename is a keyword tliat read uses to figure out how to read in the rest of the 
printed representation and construct tlie object. It is read in in package user (but it can 
contain a package prefix). The resulting symbol should citlicr have a si: read-instance 
property or be the name of a flavor diat handles the iread-instance operation. 

In the first ease, the property is applied as a function to die typename symbol itself and 
tile input stream. In the second, the handler for Uiat operation is applied to the 
operation name (as always), the typename symbol, and die input sticam (three arguments, 
but the first is implicit and not mentioned in die defmethod). self will be nil and 
instance variables should not be referred to. si:print-readably-mixin is a useful 
implementation the iread-instsnee operation for general purposes, see page 446. 

In cither ease, the handler function should read the remaining data from die sticam, and 

construct and return the datum it describes. It should return with die o character waiting 

to be read from the input stream (;untyi it if necessary), read signals an error after it is 

returned to if a d character is not next. 

♦ 

The typename can be any symbol with an appropriate property or flavor, not necessarily 
related to the type of object diat is created; but for clarity, it is good if it is the same as 
the type-of of the object printed. Since the type symbol is passed to the handler, one 
flavor’s handler can be inherited by many other flavors and can examine the type symbol 
read in to decide what flavor to construct 

#1 #I is used to comment out entire pieces of code. Such a comment begins with #| and 
ends with | #. The text in between should be one or more properly balanced p.r.’s of 
Lisp objects, possibly including nested it \.. .\# comments. This text is skipped over by 
the reader, and does not contribute to the value returned by read. 


23.4 Expression Output Functions 

These functions all take an optional argument called stream, which is where to send the 
output. If unsupplied stream defaults to the value of ‘standard-output*. If stream is nil, the 
value of ‘standard-output* (i.e. the default) is used. If it is t, the value of ‘terminal-io* is 
used (i.e. the interactive terminal). ’Fhis is all more-or-less compatible with Maclisp, except that 
instead of the variable ‘standard-output* Maclisp has several variables and complicated rules. 
For detailed documentation of streams, refer to section 22.3, page 459. 

pplnl object &optlonal stream 

Outputs the printed representation of object to stream, with escaping (see page 506). 
object is returned. 
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prinl-then-space ohjcct .fcoptional stream 

Like prin1 except that output is tcrltowcd by a spxc. 

print object &opUoni\\ stream 

I.ike prini except that output is preceded by a carriage return and followed by a space. 
abject is returned. 

pr1nc oft/rc/ &optional stream 

I.ike prini except that the output is not escaped, object is returned. 

write object &kcy stream escape radix base circle pretty level length case gensym array 

Prints object on stream, having bound all the printing flags according to the keyword 
arguments if specified. For example, the keyword argument array specifics how to bind 
*print-array*; if array is omitted, the ambient value of ‘print-array* is used. This 
function is sometimes cleaner titan binding a printing control variable explicitly. ITie value 
is object. 

23.4.1 PrcltyPrinting Output Functions 

pprint object &optional stream 

pprint is like prini except that ‘print-pretty* is bound to t so that the grinder is used, 
pprint returns zero values, just as the form (values) does. 

grindef function-spec... Macro 

Prints the definitions of one or more functions, with indentation to make the code 
readable. Certain other “pretty-printing” transformations are performed: ITte quote 
special fonn is represented with the ’ character. Displacing macros arc printed as the 
original code rather tlian the result of macro expansion. The code resulting from the 
backquote (') reader macro is represented in terms of *. 

The subforms to grindef arc the function specs whose definitions are to be printed; the 
usual way grindef is used is with a form like (grindef fod) to print the definition of foo. 
When one of these subforms is a symbol, if Uie symbol has a value its value is prettily 
printed also. Definitions arc printed as defun special fonns, and values arc printed as 
setq special forms. 

If a function is compiled, grindef says so and tries to find its previous interpreted 
definition by looking on an associated property list (sec uncompile (page 301). This 
works only if the function's interpreted definition was once in force; if the definition of 
the function was simply loaded from a QFASL file, grindef cannot not find the 
interpreted definition. 

With no subforms, grindef assumes the same arguments as when it was last called. 
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grind-top-level ohj Aoptional wUilli (.s 7 m?w;’standard-output*) iunlycypnW) 
(^//s/>/ 4 /m/’si:displaced) (/fT/)r/-/;t) noiify-fun loc 
IVctty-prints obj on stream, putting up to width characters per line. I'his is the primitive 
interface, to the pretty-printer. Note tliat it does not support variable-width fonts. If tlie 
width argument is supplied, it is how many characters wide the output is to be. If width 
is unsupplied or nil, grind-top-level tries to figure out the natural width of tlte stream, 
by sending a :size-in-characters message to tlic stream and using the first returned 
value. If tlie stream doesn’t handle tliat messiige, a width of 95. characters is used 
instead. 

The remaining optional arguments activate various strange features and usually should not 
be supplied, 'fhese options are for internal use by tlie system and are documented here 
for only completeness. If untyo-p is t, tlie :untyo and :untyo-mark operations are be 
used on stream, speeding up tlie algoritlim somewhat, displaced controls the checking for 
displacing macros; it is tlte symbol which flags a place that has been displaced, or nil to 
disable tite feature. If terpri-p is nil, grind-top-level does not advance to a fresh line, 
before printing. 

If notify-fun is non-nil, it should be a function that to be called with three arguments for 
each “token” in the pretty-printed output. Tokens are atoms, open and close parentlicses, 
and reader macro characters such as ’. The arguments given to notify-fun are tlie token, 
its “location” (see next paragraph), and t if it is an atom or nil if it is a character. 

loc is the “location” (typically a cons) whose car is obj. As the grinder recursively 
descends through the structure being printed, it keeps track of the location where each 
thing came from, for the benefit of the notify-fun. This makes it possible for a program 
to correlate the printed output with the list structure. 'ITic “location” of a close 
parenthesis is t, because close parentheses have no associated location. 


23.4.2 Non-Stream Printing Functions 

wr1te-t0-str1ng object &key escape radix base circle pretty level length case gensym 
array 

pr1nl-to-str1ng object 
pr1nc-to-str1ng object 

Like write, print and princ, respectively, but put the output in a string and return the 
string (see page 528), 

See also the with-output-to-string special form (page 474). 

The following obsolete functions are for Maclisp compatibility only. The examples use 
traditional syntax. 

exploden object 

Returns a list of characters (represented as fixnums) that arc the characters that would be 
typed out by (princ object) (i.e. the uncscaped printed representation of object). 
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Hxamplc: 

(exploden ’(+ /12 3)) => #o(50 53 40 61 62 40 63 51) 
explodec object 

Returns a list of characters represented by symbols, interned in the current package, 
whose names arc the characters Oiat would be typed out by (princ object) (i.c. die 
uncscapcd printed representation of object). 

Hxamplc: 

(explodec •(+ /12 3)) => (|(| + | !|1| |2| | | |3| |)|) 

(Note that there arc escaped spaces in die above list.) 

explode object 

Like explodec but uses die escaped printed representation. 

Hxamplc: 

(explode ’(+ /12 3)) => (|(1 + | | // |1| |2| | | |3| |)|) 
(Note that there arc escaped spaces in die above list.) 

flats 1ze object 

Returns the number of characters in the escaped printed representation of object. 
flatc object 

Returns the number of characters in the uncscapcd printed representation of object. 

23.5 Expression Input Functions 

Most expression input functions read characters from an input stream. This argument is called 
stream. If unsupplied it defaults to the value of ^standard-input*. 

All of these functions echo their input and permit editing if used on an interactive stream 
(one which supports the :rubout-handIer operation; sec below.) 

The functions accept an argument eof-option or two arguments eof-error and eof-value to tell 
them what to do if end of file is encountered instead of an object’s p.r. The functions that take 
two eof- arguments arc the Common Lisp ones. 

In functions that accept the eof-option argument, if no argument is supplied, an error is 
signaled at eof. If the argument is supplied, end of file causes the function to return diat 
argument. Note that an eof-option of nil means to return nil if the end of the file is reached; it 
is not equivalent to supplying no eof-option. 

In functions that accept two arguments eof-error and eof-value, end of file is an error if eof- 
error is non-nil or if it is unsupplied. If eof-error is nil, then the function returns eof-value at end 
of file. 

An error is always signaled if end of file is encountered in the middle of an object; for 
example, if a file docs not contain enough right parentheses to balance the left parentheses in it. 
Merc whitespace docs not count as starting an object. If a file contains a symbol or a number 
immediately followed by end-of-file, it can be read nonnally, without error; if an attempt is made 
to read further, end of file is encountered immediately and the eof- argumentfs) obeyed. 
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These end-oT-file conventions are not completely compatible with Maclisp. Maclisp’s deviations 
frt)m til is arc generally considered to be bugs ratlicr titan features. 

For Maclisp compatibility, nil as the stream argument also means to use Utc value of 
‘standard-input*, and t as die stream argurncrit means to use tlic value of *terminal-io*. 'This 
is only advertised to work in functions that Maclisp has, and should not be written in new 
programs. Instead of the variable ‘standard-input* Maclisp has several variables and complicated 
rules. For detailed documentiition (vf streams, refer to section 22.3, page 459. 

'The functions below that take stream and eof-optkm arguments can also be called with the 
stream and cof-option in die other order. This functionality is only for compatibility with old 
Maclisp programs, and should never be used in new programs. ’The functions attempt to figure 
out which way they were called by seeing whether each argument is a plausible stream. 
Unfortunately, there is an ambiguity with symbols: a symbol might be a stream and it might be 
an cof-option. If there arc two arguments, one being a symbol and the other being something 
dtat is a valid stream, or only one argument, which is a symbol, then these functions interpret 
die symbol as an cof-option instead of as a stream. To force them to interpret a symbol as a 
stream, give the symbol an si:io-stream-p property whose value is t. 

read &optional stream eof-option ruboul-handler^options 

Reads the printed representation of a Lisp object from stream, builds a corresponding 
Lisp object, and returns the object, rubout-haudler'options are used as options for the 
rubout handler, if stream supports one; see section 22.5, page 500 for more information 
on this. 

cl 1 tread &opdonal stream (eof-errorpX) eofvalue recursive-p 

The Common Lisp version of read differs only in how its arguments are passed. 

recursive-p should be non-nil when calling from the reader or from the defining function 
of a read-macro character; that is, when reading a subexpression as part of the task of 
reading a larger expression. This has two effects: the subexpression is allowed to share 
labels with the containing expression, and whitespace which terminates the 
subexpression (if it iS a symbol or number) is not discarded. 

read-or-end &optional stream eof-option rubout-handler-options 

Like read, but on an interactive stream if the input is just the character End it returns 
the two values nil and :end. 

read-pr8serve-de11m1ters Variable 

Certain printed representations given to read, notably those of symbols and numbers, 
require a delimiting character after them. (Lists do not, because the matching close- 
parenthesis serves to mark the end of the list.) Normally read throws away the delimiting 
character if it is whitespace, but preserves it (using the :untyi stream operation) if the 
character is syntactically meaningful, since it may be the start of the next expression. 

If read-preserve-delimiters is bound to t around a call to read, die delimiting character 
is never thrown away, even if it is whitespace. This may be useful for certain reader 
macros or special syntaxes. 
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read-preservlng-whltespace &opiional stream {eof-errorpX) cof-valuc rccursive-p 

Like cli:read bill binds read-preserve-delimiters to t. This is tlic Common I/isp way of 
requesting the read-preserve-delimiters feature. 

read^del tmlted-l 1st char &optionaI stream recursive-p 

Reads expressions from stream until Uie character char is seen at top level when an 
expression is expected; then returns a list of the objects read, char may be a fixnum or a 
character object. For example, if char is #/], and the text to be read from stream is a 
(b e)] ... then tlic objects a and {b c) arc read, the ] is seen as a terminator and 
discarded, and the value returned is (a (b c)). recursive-p is as for cihread. Hnd of file 
within this function is always an error since it is always “witliin an object”—-the object 
whose textual representation is terminated by char. 

Note tliat use of tJiis function docs not cause char to terminate tokens. Usually you want 
that to happen, but it is purely under the control of tlic rcadtablc. So you must modify 
the rcadtablc to make this so. 'Lhc usual way is to define char as a macro character 
vhosc defining fimetion just signals an error. The defining function is not called when 
char is encountered in tlic expected context by read-delimited-list: if char is encountered 
anywhere else, it is an unbalanced bracket and an error is appropriate. 

read-for-top-levol &optional stream eof-option 

This is a slightly dificrent version of read. It differs from read only in that it ignores 
close-parentheses seen at top level, and it returns tlie symbol si:eof if tlie stream reaches 
end-of-file if you have not supplied an eof-option (instead of signalling an error as read 
would). 'I’his version of read is used in tlie system’s “read-cval-print” loops. 

read-check-indentation &optional stream eof-option 

This is like read, but validates tlic input based on indentation. It assumes that the input 
data is formatted to follow the usual convention for source files, that an open-parenthesis 
in column zero indicates a top-level list (with certain specific exceptions). An open- 
parenthesis in column z.cro encountered in the middle of a list is more likely to result 
from close-parentheses missing before it than from a mistake in indentation. 

If read-check-indentation finds an open-parenthesis following a return character in the 
middle of a list, it invents enough close-parentheses to close off all pending lists, and 
returns. The offending open-parcntliesis is :untyi’d so it can begin the next list, as it 
probably should. End of file in tlic middle of a list is handled likewise. 

read-check-indentation notifies the caller of the incorrect formatting by signaling the 
condition sysimissing-closeparen. 'this is how the compiler is able to record a warning 
about the missing parentheses. If a condition handler proceeds, read goes ahead and 
invents close-parentheses. 

There are a few special forms that arc customarily used around function definitions—for 
example, eval-when, local-declare, and comment. Since it is desirable to begin the 
function definitions in column zero anyway, read-check-indentation allows a list to 
begin in column zero within one of tlicse special forms, A non-nil si:may-surround- 
defun property identifies the symbols for which this is allowed. 
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read-check-Indentation 


Variable 


I'his variable is non-nil during a read in which indenuaion is being checked. 


23.5.1 Non-Stream Parsing Functions 

I'hc following functions do expression input but get the characters from a string or a list 
instead of a stream. 

read-from-strlng siring &optional eoj-opiion (siariO) end 

The characters of siring arc given successively to tlic reader, and the Lisp object built by 
the reader is returned. Macro characters and so on all take eft’cct. If siring has a fill- 
pointer it controls how much can be read. 

eof-opiion is what to return if the end of the string is reached, as in read, siari is tlie 
index in the string of the first character to be read, end is the index at which to stop 
reading; that point is treated as end of file. 

read-from-string returns two values; the first is tlie object read and the second is the 
index of the first character in the string not read. If the entire string was read, this is the 
lengtli of the string. 

Example: 

(read-from-string "(a b c)”) => (a b c) and 7 

c11:r9ad-fPom-str1ng s/r/«g &optional (eof-errorpi) eof-value &key (siariO) end 
preserve-whUespace 

The Common Lisp version of read-from-string uses a different calling convention. The 
arguments mean the same thing but are arranged differently. ITiere are three arguments 
with no counterparts: eof-errorp and eof-value, which are simply passed on to cli:read, 
and preserve-whitespace, which if non-nil means that the reading is done with read- 
preserve-delimiters bound to t. 

See also the with-input-from-string special form (page 473). 

parse-Integer string &key (start0) end (radix^0.) junk-allowed 

Parses the contents of string (or the portion from start to end) as a numeral for an integer 
using the specified radix, and returns the integer. Radices larger than ten are allowed, 
and they use letters as digits beyond 9. Leading whitespace is always allowed and 
ignored. A leading sign is also allowed and considered part of the number. 

When Junk-allowed is nil, the entire specified portion of string must consist of an integer 
and leading and trailing whitespace. Otherwise, an error happens. 

If junk-allowed \s, non-nil, parsing just stops when a non-digit is encountered. The 
number parsed so far is returned as the first value, and the index in string at which 
parsing stopped is returned as the second value. Tliis number equals end (or the length of 
string) if there is nothing but a number. If non-digits are found without finding a 
number first, the first value is nil. Examples: 


PS:<L.MAN>RDPRT.1EXT.29 


8-JUN-84 



i-■xp|■ossioll Input l-'iinctions 


534 l.isp Miichinc Miinual 


(parse-integer " lA " :radix 16.) => 26. 

(parse-integer " 15X " :end 3) => 15. 

(parse-integer " -15X " ;junk-a1lowed t) => -15. 3 
(parse-integer " 15X ") => error! 

readllst char-list 

This function is provided mainly for Maclisp compatibility, char-list is a list of characters. 
The characters may be represented by anything tliat tltc function character accepts; 
character objects, fixnums, strings, or symbols. Ihc characters arc given successively to 
die reader, and tire l.isp object built by tlie reader is returned. Macro characters and so 
on all uikc effect. 

If there arc more characters in char-list beyond those needed to define an object, the 
extra characters arc ignored. If there are not enough characters, some kind of sys:read- 
end-of-file error is signaled. 

23.5.2 input Error Conditions 

sys: read-error (sys:parse-error error) Condition 

'fhis condition name classifies all errors detected by the reader per se. Since sysiparse- 
error is implied, all sys:read-error errors must provide tlie proceed type ;no-action so 
that automatic proceed is possible if the error happens during compilation. Sec page 505. 

Since this condition name implies sys:parse-error and error, those two are not 
mentioned as implications below when sys:read-error is. 

sys:read-end-of-f He (sys:read-error sys:end-of-file) Condition 

Whenever the reader signals an error for end of file, the condition object possesses this 
condition name. 

Since sys:end-of-file is implied, the :stream operation on the condition instance returns 
the stream on which end of file was reached. 

sys: read-1 ist-end-of-f He Condition 

(sys:read-end-of-fiIe sys:read-error sys:end-of-file) 

This condition is signaled when read detects end of file in the middle of a list 

In addition to the :stream operation provided because sys:end-of-file is one of the 
proceed types, the condition instance supports the ;list operation, which returns the list 
read so far. 

Proceed type :no-action is provided. If it is used, the reader invents a close-parenthesis 
to close off the list. Within read-check-indentation, the reader signals the error only 
once, no matter how many levels of list arc unterminated. 
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sys: read-stPing-end-of *f ilo Comiiiion 

(sys:read-end-of-file sys:read-error sys:end-of-file) 

This is signaled when read delects end of file in the middle of a string delimited by 
double-quotes. 

riic rstring operation on the condition insumcc returns tlte string read so far. 

Proceed type ;no-aetion terminates the string and returns. If the string is within other 
ct)nstructs tliat are unlemiinated, another end of file error is will be signaled later. 

sys; read-symbol-end-of-file Condition 

(sys:read-end-of-file sysrread-error sys:end-of-file) 

This is signaled when read detects end of file within a multiple escape construct. 

The :string operation on tlic condition instance returns the print name read so far. 

Proceed type :no-action terminates the symbol and returns. If the symbol is within other 
constructs that are unterminated, another end of file error is will be signaled later. 

sys:m1ss1ng-c1oseparen (condition) Condition 

I'his condition, which is not an error, is signaled when read-check-indentation finds an 
open-parenthesis in column zero within a list 

Proceed type :no-action is provided, On proceeding, the reader invents enough close- 
parentheses to close off all the lists that are pending. 

23.6 TheRcadtable 

ITie syntax used by the reader is controlled by a data structure called the readtable. (Some 
aspects of printing are also controlled by the readtable.) ITiere can be many readtables, but the 
one that is used is the one which is the value of ‘readtable*. A particular syntax can be 
selected for use by setting or binding ‘readtable* to a readtable which specifies that syntax 
before reading or printing. In particular, this is how Common Lisp or traditional syntax is 
selected. ITie readtable also controls the symbol substitutions which implement the distinction 
between the traditional and Common Lisp versions of functions such as subst, memberand 
defstruct. 

The functions in this section allow you to modify the syntax of individual characters in a 
readtable in limited ways. You can also copy a readtable; then you can modify one copy and 
leave the other unchanged. 

A readtables may have one or more names. Named readtables are recorded in a central data 
base so that you can find a readtable by name. When you copy a readtable, the new one is 
anonymous and is not recorded in the data base. 
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readtabls Variable 

•readtable* Variable 

The value of readtable or *readtable* is the current rcaduiblc. 'llus starts out as the 
initial standard rcadUiblc. You can bind Uiis variable to change temporarily the readuiblc 
being used. 

'I’he two names are synonymous. 

s1 :standard-readtab1e Consiaiu 

This is copied into ’readtable* every time the machine is booted. Therefore, it is 
normally the same as ’readtable* unless you make ’readtable* be some other readtable. 
If you alter die contents (if ’readtable’ without setting or binding it to some other 
readutble, tliis readtable is changed. 

s1: Initial-readtable Constant 

The value of si.initial-readtable is a read-only copy of the default current rcadtablc. Its 
purpose is to preserve a copy of tlie standard read syntax in case you modify the contents 
of ’readtable’ and regret it later. You could use sianitial-readtable as the from- 
readtable argument to copy-readtable or set-syntax-from-char to restore all or part of 
tlic standard syntax. 

s1 :common-Hsp-readtable Constant 

A rcadtablc which initially is set up to define Common Lisp read syntax. Reading of 
Common Lisp programs is done using this readtable. 

si: 1nit1al-common-Hsp-peadtable Constant 

A read-only copy of si:common-lisp-readtable, whose purpose is to preserve a copy of 
tlic standard Common Lisp syntax in case you modify si:common-lisp-readtable (such 
as, by reading a Common Lisp program which modifies the current readtable). 

si: rdtbl-names readtable 

Returns tlic list of names of readtable. You may setf this to add or remove names. 

si;find-readtable-named name 

Returns the rcadtablc named name, or nil if none is recorded. 

readtablep object 

t if object is a readtable. 

The user can program the reader by changing the readtable in any of three ways. The syntax 
of a character can be set to one of several predefined possibilities. A character can be made into 
a macro character, whose inlcrprcLation is controlled by a user-supplied function which is called 
when tlie character is read, 'fhe user can create a completely new readtable. using the readtable 
compiler (SYS; 10; RTC LISP) to define new kinds of syntax and to assign syntax classes to 
characters. Use of the rcadtablc compiler is not documented here. 
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copy-readtable Aoptional fivm-remltable lo-readlable 

fnm-reaJiabIc, which defaults to the current readtable. is copied. If from-rcadiable is nil, 
the standard CoiTini()n Lisp synUix is copied. If lo-readlable is unsupplied or nil, a fresh 
copy is made. Otherwise lo-readiable is clobbered with the copied syntax. 

Use copy-readtable to get a private rcaduiblc before using the following functions to 
change tlic syntax of characters in it. I’hc value of *readtable* at tlic start of a l.isp 
Machine session is the initial standard rcadUiblc, which usually should not be modified. 


set-syntax-from-char lo-char from-char &optional lo-readlable from-readlable 

Copies the syntax of from-char in from-readlable to character lo-char in lo-readlable. lo- 
readlable defaults to tlic current readable and from-readlable defaults to sirinitial- 
standard-readtable (standard traditional syntax). 

cl i: set-syntax-from-char lo-char from-char &optional lo-rcadlable from-readlable 

Is a Common Lisp function which copies the syntax of from-char in from-readlable to 
character to-c/wr in lo-readidble. lo-readlable defaults to tlie current readtable and from- 
readlable defaults to si:initial-common-lisp-readtable (standard Common Lisp syntax). 

Common Lisp has a peculiar idea of what it means to copy the syntax of a character. 
3’hc only aspect of syntax that tlic readtable supposedly specifies is tlic choice among 

* token constituent: digits, letters, random things like !, $, and also colon! 

* whitespace: spaces, Tab, Return. 

* single escape character: / traditionally, \ in Common Lisp. 

* multiple escape character: vertical-bar. 

* macro character: standardly ()",.’*; 

* nonterminating macro character: # is the only such character standardly defined. 

The differences among macro characters are determined entirely by the fiinctions that they 
invoke. The differences among token constituents (including the difference between A and 
colon) are fixed! You can make A be a macro character, or whitespace, or a quote 
character, but if you make it a token constituent then it always behaves the way it 
normally does. You can make colon be a macro character, or whitespace, etc., but if it 
is a token constituent it always delimits package names. If you make open-parenthesis 
into a token constituent, there is only one kind of token constituent it can be (it forces 
the token to be a symbol, like $ or @ or %). 

This is not how Lisp Machine readtables really work, but since cli:set-syntax-from-char 
is provided just for Common Lisp, the behavior specified by Common Lisp is laboriously 
provided. So, if from-char is some kind of token constituent, this function makes to-char 
into a token constituent of the kind that lo-char is supposed to be—not the kind of token 
constituent that from-char is. 

By contrast, the non-Common-Lisp set-syntax-from-char would make to-char have 
exactly the same syntactic properties that from-char has. 
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set-character-translation /ronn-har to-diar &optionaI muUable 

Changes rmlluhlc so that fwm-char will l)c translated to lo-cfuir upon read-in, when 
muitabic is the current rcadtiiblc. This is normally used only for translating lower ease 
letters to upper case. Chanjcier translation is inhibited by escape characters and within 
strings, muitabic defaults to the current readtable. 

The following syntax-setting functions arc more or less obsolete. 

set-syntax-from-descr1pt1on char description &optional readtable 

Sets the syntax of char in readtable to be tliat described by the symbol description, 
readtable defaults to the current rcaduiblc. 

Hach readtable has its own set of descriptions which it defines. The following descriptions 
arc defined in the standard rcadUible: 

si:alphabetic An ordinary character such as ‘A’. 

silbreak A token separator such as (Obviously left parcntlicsis has other 

properties besides being a break. 

si:whitespace A token separator that can be ignored, such as ‘ ’. 

si:single A self-delimiting single-character symbol. The initial readtable 

does not contain any of these. 

si:escape The character quoier. In tlic initial readtable this is V’. 

si:multipte-escape 'fhe symbol print-name quoter. In the initial readtable this is T* 

si:macro A macro character. Don’t use this; use set-macro-character 

(page 540). 

Simon -terminating - macro 

A macro character recognized only at the start of a token. In the 
initial readtable, is such a character. (It is also a dispatching 
macro, but that is another matter.) Tlic correct way to make a 
character be a macro is with set-macro-character. 

si:character-code-escape 

Tlic octal escape for special characters. In the initial^ readtable this 
is 

sirdigitscale a character for shifting an integer by digits. In the initial 

readtable this is 

sirbitscale A character for shifting an integer by bits. In the initial readtable 

this is (underscore). 

si:slash 

si:circlecross Obsolete synonyms for si:escape and si:character-code-escape. c 

Unfortunately it is no longer possible to provide si:doublequote as double-quote is now 
an ordinary macro character. 
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These symbols may be moved to tlic keyword package at soinc point, 
set syntax character arg2 argS 

This exists only for Maclisp compatibility. The above functions arc preferred in new 
programs. The syntax of character is altered in the current rcadtablc, according to arg2 
and arg3. character can be a fixnum, a symbol, or a string, i.e. anything acceptable to 
the character function. arg2 is usually a keyword; it can be in any package since this is 
a Maclisp compatibility function, llie following values are allowed for arg2: 

:macro The character becomes a macro character. arg3 is the name of a function 

to be invoked when this character is read. I'hc fiinction takes no 
arguments, may tyi or read from ’standard-input* (i.e. may call tyi or 
read without specifying a stream), and returns an object which is taken as 
tlie result of the read. 

:splicing Like :macro but the object returned by the macro funQiion is a list that is 
nconced into the list being read. If the character is read anywhere except 
inside a list (at top level or after a dotted-pair dot), then it may return (), 
which means it is ignored, or (obj), which means that obj is read. 

;single ITie character becomes a self-delimiting single-character symbol. If arg3 is 

a fixnum, the character is translated to that character. 

nil The syntax of tlie character is not changed, but if arg3 is a fixnum, the 

character is translated to that character. 

a symbol The syntax of the character is changed to be the same as that of the 
character arg2 in the standard initial rcadtablc. arg2 is converted to a 
character by taking the first character of its print name. Also if arg3 is a 
fixnum, the character is translated to that character. 


23.7 Read-Macro Characters 

A read-macro character (or just macro character) is a character whose syntax is defined by a 
function which the reader calls whenever that character is seen (unless it is escaped). This 
function can optionally read additional characters and is then responsible for returning the object 
which they represent. 

The standard meanings of the characters open-parenthesis, semicolon, single-quote, double¬ 
quote, #, backquote (') and comma are implemented by making them macro characters. 

For example, open-parenthesis is implemented as a macro character whose defining function 
reads expressions until a close-parenthesis is found, throws away the close-parenthesis, and returns 
a list of the expressions read. (It actually must be more complicated than this in order to deal 
properly with dotted lists and with indentation checking.) Semicolon is implemented as a macro 
character whose defining function swallows characters until a Return and tlicn returns no values. 

Close-parenthesis and close-horseshoe (d) are' also macro characters so that they will terminate 
symbols. Their defining functions signal errors if actually called; but when these delimiters are 
encountered in their legitimate contexts they are recognized and handled specially before the 
defining function is called. 
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I'hc user can also define macro characters. 

Wlicn a macro's defining functitrn is called, it receives two arguments: the input stream, and 
the macro character being handled. The function may read characters from tlie stream, and 
should return zero or more values, which arc the objects that the macro construct “reads as”. 
Zero values causes the macro construct to be ignored (the semicolon macro character docs tliis), 
and one value causes die macro construct to read as a single object (most macro characters do 
til is). More than one value is allowed only within a list. 

Macro characters may be lerminaiiiig or non-ienuiiiating. A non-tcmiinating macro character 
is only recognized as a macro character when it appears at the beginning of a token, if it appears 
when a token is already in progress, it is treated as a symbol constituent. Of the suindard macro 
characters, all but arc tenninating. 

One kind of macro character is tlie dispalch macro character. 'I’his kind of character is 
handled by reading one more character, converting it to upper case, and looking it up in a table. 
Thiis, tl dispatch macro character is tlie start of a two-character sequence, with which is 
asserciated a defining ftinction. # is tlie only standardly defined dispatch macro character. 

When a dispatch macfo character is used, it may be followed by a decimal integer which 
serves as a parameter, 'flie character for the dispatch is actually the first non-digit seen. 

'I'he defining function for a dispatch macro two-character sequence is almost like that of an 
ordinary macro character. However, it receives one more argument. 'I’his is the parameter, the 
decimal integer that followed tlie dispatch macro character, or nil if no parameter was written. 
Also, the second argument is tlie subdispatch character, the second character of the sequence. 
'I'he dispatch macro character itself is not available. 

set-macro-character char function &optional non-terminating-p in-rcadtable 

Sets the syntax of character char in readtable in-readtable to be that of a maero character 
which is handled by function. When that character is read by read, function is called. 

char is made a non-terminating macro character if non-tenninating-p is non-nil, a 
terminating one otherwise. 

get-macro-character char in-readtable 

Returns two values that describe tlie macro character status of char in in-readtable. If 
char is not a macro character, both values are nil. Otherwise, the first value is the 
function and tlie second value is the non-tenninating-p for this character. 

Those two values, passed to set-macro-character, are usually sufficient to recreate^ 
exactly the syntax char has now; however, since one of the arguments tliat the function 
receives is tlie macro character that invoked it, it may not behave the same if installed on 
a different character or in a different readtable. In particular, the definition of a dispatch 
macro character is a standard function that looks tlie macro character up in the readtable. 
Thus, the definition only records tliat the macro character is a dispatch macro character; 
it does not say what subcharacters are allowed or what they mean. 
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make-dlspatch-macro-character char &optional iioii-tcmiinalina-p in-rcmilable 

Makes char be a dispatch macro character in iii-rcadiablc. This means dial when char is 
seen read will read one more chtiracter to decide what to do. # is an example of a 
dispatch macro character, non-ieritmaiing-p means the same thing as in set-macro¬ 
character. 

set-dlspatch-macro-character char subchar function &optional in-readtable ' 

Sets die syntax of the two-character sequence, char subchar, assuming that char is already 
a dispatch macro character, function becomes die defining function for this sequence. 


If subchar is lower case, it is converted to upper case. Case is never significant for the 
character that follows a dispatch lUiicro character. The decimal digits may not be defined 
as subchars since diey are always used for infix numeric arguments as in #5r. 


get-dlspatch-macro-character char subchar &optional in-readtable 

Returns the function for subchar following dispatch macro character char in leadtablc in- 
readtable. The value is nil if subchar is not defined for following char. 


'fliese subroutines are for use by the defining flinctions of macro characters. Ordinary read 
should not be used for reading subexpressions, and the ordinary :tyi operation or ftinctions read- 
char or tyi should not be used for single-character input. The functions below should be used 
instead. 


s1: read-recursive &opiional stream 

Equivalent to (cli:read stream t nil t). See page 531. 'Fhis is the recommended way for a 
macro character’s defining function to read a subexpression. 

s1:xr-xrty1 stream ignore-whitespace no-chars-special no-muUiple-escapes 

Reads the next input character from stream, for a macro character’s defining function. If 
ignore-whitespace is non-nil, any whitespace characters seen arc discarded and the first 
non-whitespace character is returned. 

The first value is the character as translated; the third value is the original character, 
before translation. ITie second value is a syntax code which is of no interest to users 
except to be passed to si:xr-xruntyi if this character must be unread. 

Normally, this function processes all the escape characters, and performs translations (such 
as from lower case letters to upper case letters) on characters not escaped. Font specifiers 
(epsilons followed by digits or •) are ignored if the file is formatted using them. 

If no-multiple-escapes is non-nil, multiple escapes (vertical bar characters) are not 
processed; they are returned to the caller, 'fhis mode is used for reading the contents of 
strings. If no-chars-special is non-nil, no escape characters arc processed. All characters 
are simply returned to the caller (except that font specifiers are still discarded if 
appropriate). 
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si:xr-xrunty1 sinwn char nuin 

Unreads char, for a macro character’s defining function, char should be tlie tliird value 
returned by the last call to si:xr-xrtyi, and man should be tlie second value. 

*read-suppress* Variable 

If tliis variable is non-nil, all the standard read functions and macro characters do their 
best to avoid any errors, and any side effects except for removing characters from the 
input stream. For example, syinbols arc not interned to avoid cither errors (for 
nonexistent packages) or side effects (adding new symbols to packages). In fact, nil is 
used in place of any symbol Uiat is written. 

User macro characters should also notice this variable when appropriate. 

'fhe purpose of the variable is to allow expressions to be skipped and discarded. 'ITie 
read-time conditional constnicts #+ and #- bind it to t to skip tlie following expression if 
it is not wanted. 

'fhe following functions for defining macro characters are more or less obsolete. 

set-syntax-macro-chap char function &optional readtable 

Changes readtable so that char is a macro character. When char is read. Junction is 
called, readtable defaults to the current readtable. 

function is called with two arguments, list-so-far and the input stream. When a list is 
being read, list-so-far is tliat list (nil if tliis is the first clement). At the top level of read, 
list-so-far is the symbol doplevel. After a dotted-pair dot, list-so-far is tlie symbol :after- 
dot. function may read any number of characters from the input stream and process them 
however it likes, 

function should return three values, called thing, type, and splice-p. thing is the object 
read. If splice-p is nil, thing is the result. If splice-p is non-nil, then when reading a list 
thing replaces the list being read—often it will be list-so-far with something else neone’ed 
onto the end. At top-level and after a dot, if splice-p is non-nil the thing is ignored and 
the macro-character docs not contribute anything to the result of read, type is a historical 
artifact and is not really used; nil is a safe value. Most macro character functions return 
just one value and let tlie other two default to nil. 

Note that tlie convention for values returned by function is different from that used for 
functions specified in set-macro-character, above, set-syntax-macro-char works by 
encapsulating function in a closure to convert the values to the sort that set-macro¬ 
character wants and then passing the closure to set-macro-character. 

function should not have any side-effects other than on the stream and list-so-far. Because 
of the way tlie rubout-handler works, function can be called several times during the 
reading of a single expression in which the macro character only appears once. 

char is given the same syntax tliat single-quote, backquote, and comma have in tlie initial 
readtable (it is called :macro syntax). 
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S0t-syntax-#-macro-char chor fund ion &optional readlable 

Causes fundioii to be called when is read, readlable deftndts to tlie current 

rcadurblc. 'Hie function’s arguments and return values arc the same as for normal macro 
characters, documented above. When funetion is called, die special variable si:xr-sharp- 
argument contains nil or a number that is tlic number or special bits between the # and 
char. 

setsyntax-shapp-macro character type funetion &optional readlable 

This exists only for Maclisp compatibility, set-dispatch-macro-character should be 
used instead. If function is nil, if character is turned off, otherwise it becomes a macro 
tliat calls function, type can be :macro, :peek-macro, isplicing, or :peek-splicing. I'hc 
splicing part controls whether funetion returns a single object or a list of objects. 
Specifying peek causes character to remain in tltc input stream when funetion is called; 
tliis is useful if character is something like a left parenthesis, function gets one argument, 
which is nil or die number between die # and the character. 

23.8 The :rcad and :prlnt Stream Operations 

A stream can specially handle the reading and printing of objects by handling the :read and 
:print stream operations. Note that diese operations arc optional and most streams do not support 
them. 

If the read function is given a stream that has :read in its which-operations, then instead of 
reading in the normal way it sends the :read message to the stream with one argument, read’s 
eofoption if it had one or a magic internal marker if it didn't. Whatever the stream returns is 
what read returns. If the stream wants to implement the :read operation by internally calling 
read, it must use a different stream that does not have :read in its which-operations. 

If a stream has :print in its which-operations, it may intercept all object printing operations, 
including those due to the print, prin1, and princ functions, tliose due to format, and those 
used internally, for instance in printing the elements of a list. The stream receives the ;print 
message with three arguments: the object being printed, the depth (for comparison against the 
‘print-level* variable), and escape-p (which is the value of ‘print-escape*). If the stream 
returns nil, then normal printing takes place as usual. If the stream returns non-nil, then print 
does nothing; the stream is assumed to have output an appropriate printed representation for the 
object. The two following functions are useful in this connection; however, they are in the 
system-internals package and may be changed without much notice. 

sirprint-object object depth stream &optional which-operations 

Outputs the printed-representation of object to stream, as modified by depth and the 
values of the ‘print-... variables. 

This is the internal guts of the Lisp printer. When a stream’s print handler calls this 
function, it should supply the list (:string-out) for which-operations, to prevent itself from 
being called recursively. Or it can supply nil if it does not want to receive :string-out 
messages. 
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If you want to ciistonii/,c the behaviorof all printing of l.isp objects, advising (see section 
30.10, page 742) this function is the way to do it. See section 23.1, page 513. 

s1:print-Hst list depth stream whkh-operatiom 

This is the part of the l.isp printer that prints lists. A stream's :print handler can call this 
function, passing along its own arguments and its own which-operatioris, to arrange for a 
list to be printed the nonnal way and die stream’s ;print hook to get a chance at each of 
die list's elements. 
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24. Naming of Files 

A I.isp Machine generally has access to many file systems. While it may have its own file 
system on its own disks, usually a community of Lisp Machine users want to have a shared file 
system accessible by any of the Lisp Miichines over a network. Hiese shared file systems can be 
implemented by any computer Uiat is capable of providing file system service. A file server 
computer may be a special-purpose computer Uiat does noiliing but service file system requests 
from computers on a netwt)rk, or it may be a time-sharing system. 

Programs need to use names to designate files within tliese file systems. The main dilficulty in 
dealing with names of files is that different file systems have different naming fonnats for files. 
For example, in the ITS file system, a typical name looks like: 

DSK: GEORGE; FOO QFASL 

with DSK being a device name, GEORGE being a directory name, FOO being tlie first file name 
and QFASL being the second file name. Flowcvcr, in 'fOPS-20, a similar file name is expressed 
as: 

PS:<GE0RGE>F00.QFASL 

It would be unreasonable for each program that deals with file names to be expected to know 
about each different file name format that exists, or new formats that could get added in the 
future. However, existing programs should retain their abilities to manipulate the names. 

The functions and flavors described in this chapter exist to solve this problem. They provide 
an interface through which a program can deal with names of files and manipulate them without 
depending on anything about their syntax. ITiis lets a program deal with multiple remote file 
servers simultaneously, using a uniform set of conventions. 

24.1 Pathnames 

All file systems dealt with by the Lisp Machine are mapped into a common model, in which 
files are named by something called a pathname. A pathname always has six components, each 
with a standard meaning. These components are the common interface that allows programs to 
work tlie same way with different file systems; the mapping of the pathname components into the 
concepts peculiar to each file system is taken care of by the pathname software. Pathname 
components are described in the following section, and the mappings between components and 
user syntax is described for each file system later in this chapter. 

pathnamep object 

t if object is a pathname. 

A pathname is an instance of a flavor (see chapter 21, page 401); exactly which flavor 
depends on what the host of the pathname is, but pathname is always one of its component 
flavors. If p is a pathname, then (typep p ’pathname) returns t. One of the messages handled 
by host objects is the :pathname-flavor operation, which returns the name of the flavor to use 
for pathnames on that host. And one of the differences between host flavors is how they handle 
this operation. 
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I'hcrc are funcliuns for manipulating pathnames, and there arc also messages that can be sent 
to them, riicsc arc described later in this chapter. 

Two important operations of the pathname system arc parsing and merging. Parsing is the 
conversion of a string—which might be something typed in by die user when asked to supply die 
name of a file—into a pathname trbjeet. I his involves finding out what host die pathname is for, 
dien using the file name syntax conventions of that host to parse the string into the standard 
pathname eomponents. Merging is the operation dial takes a padinamc with missing components 
and supplies values for diose components from a set of defaults. 


riie function string, applied to a pathname, converts it into a string diat is in the file name 
syntax of its host's file system, except dial die name of the host followed by a colon is inserted at 
the front. This is die inverse of parsing, princ of a pathname also docs diis, then prints the 
contents of the string. Flavor operations such as ;string-for-dired exist which convert all or part 
of a padinamc to a string in other fashions that arc designed for specific applications, prinl of a 
padinamc prints the padinamc using die #c syntax so it can be read back in to produce an 
equivalent padinamc (or die same padinamc, if read in the same session). 


Since each kind of file server can have its own character string representation of names of its 
files, there has to be a dilferent parser for each of dicsc representations, capable of examining 
such a character string and figuring out what each component is. The parsers all work differently. 
How can the parsing operation know which parser to use? The first thing that the parser docs is 
to figure out which host diis filename belongs to. A filename character string may specify a host 
explicitly by having die name of the host, followed by a, colon, at either the beginning or the 
end of the string. For example, the following strings all specify hosts cxplicidy; 


1'his specifics host AI. 
So docs this. 

So does this. 

So does this. 

This specifies host EE. 
So docs this. 


AI: COMMON; GEE WHIZ 
COMMON: GEE WHIZ AI: 

AI: ARC: USERS 1: FOO BAR 
ARC: USERSl; FOO BAR AI: 

EE:PS:<C0MM0N>GEE.WHIZ.5 
PS:<C0MM0N>GEE.WHIZ.5 EE: 

If the string docs not specify a host explicidy, the parser chooses a host by default and uses the 
syntax for that host. The optional arguments passed to the parsing function (fsrparse-pathname) 
tell it which host to assume. Note: die parser is not confused by strings starting with DSK: or 
PS: because it knows that neither of diose is a valid host name. But if the default host has a 
device whose name happens to match the name of some host, you can prevent the device name 
from being misinterpreted as a host name by writing an extra colon at die beginning of the string: 
For example. :EE:<RMS>FOO.BAR refers to the device EE on the default host (assumed to use 
'rOPS-20 syntax) rather than to die host named EE. 


Pathnames are kept unique, like symbols, so diat diere is only one object with a given set of 
components. This is useful because a padinamc object has a property list (sec section 5.10, page 
113) on which you can store properties describing die file or family of files that the pathname 
represents, '("he uniqueness implies that each time die same components arc typed in, the 
program gets the same pathname object and finds there die properties it ought to find. 


Note that a pathname is not necessarily the name of a specific file. Rather, it is a way to get 
to a file; a pathname need not correspond to any file that actually exists, and more dian one 
pathname can refer to the same file. For example, the padinamc with :newest as its version 
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refers to tJie same file as a pathname which has the appropriate number as tlic version. In 
systems with links, multiple file names, logical devices, etc., two patlinames tliat look quite 
different may really turn out to address tlie same file. To get from a patliname to a file requires 
doing a file system operation such as open. 

When you want to store properties describing an individual file, use die pathname you get by 
sending :truename to a stream rather than the pathname you open. This avoids problems with 
different pathnames that refer to die same file. 

To get a unique pathname object representing a family of files, send die messrige :generic- 
pathname to a padiname for any file in die family (see section 24.5, page 561). 

24.2 Pathname Components 

These are the components of a padiname. They are clarified by an example below. 

host An object diat represents the file system machine on which the file resides. A 

host object is an instance of a flavor one of whose components is si:basic-host. 
ITie precise flavor varies depending on the type of file system and how die files 
are to be accessed. 

device Corresponds to the “device” or “file structure” concept in many host file systems. 

directory The name of a group of related files belonging to a single user or project. 

Corresponds to the “directory” concept in many host file systems. 

name The name of a group of files that can be thought of as conceptually the “same” 

file. Many host file systems have a concept of “name” which maps directly into 
this component. 

type Corresponds to the “filetype” or “extension” concept in many host file systems. 

This says what kind of file this is; such as, a Lisp source file, a QFASL file, etc. 

version Corresponds to the “version number” concept in many host file systems. This is a 

number that increments every dme the file is modified. Some host systems do not 

support version numbers. 

As an example, consider a Lisp program named CONCH. If it belongs to GEORGE, who 
uses the FISH machine, the host would be the host-object for the machine FISH, the device 
would probably be the default and the directory would be GEORGE. On this directory would be 
a number of files related to the CONCH program. ITie source code for this program would live 
in a set of files with name CONCH, type LISP, and versions 1, 2, 3, etc. ITie compiled form 
of the program would live in files named CONCH with type QFASL; each would have the same 
version number as the source file that it came from. If the program had a documentation file, it 
would have type INFO. 

Not all of the components of a pathname need to be specified. If a component of a 
pathname is missing, its value is nil. Before a file server can do anything interesting with a file, 
such as opening the file, all the missing components of a pathname must be filled in from 
defaults. But pathnames with missing components are often handed around inside the machine, 
since almost all pathnames typed by users do not specify all the components explicitly. The host 
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is not allowed to be missing from any pathname: since tlie behavior of a patlmamc is host- 
dependent to some extent, it has to know what its host is. All pathnames have host attributes, 
even if the string being parsed does not specify one explicitly. 

A component of a pathname can also be the special symbol :unspecific. :unspecific means, 
explicitly, "this component has been specified as missing", whereas nil means that tlie component 
was not specified and should default. In merging, :unspecific counts as a specified component 
and is not replaced by a default. :unspecific docs not mean “unspecified”: it is unfortunate that 
those two words arc similar. 

:unspecific is used in generic pathnames, which refer not to a file but to a whole family of 
files. The version, and usually the type, of a generic pathname arc :unspecific. Another way 
:unspecific is used has to do with mapping of patlinamcs into file systems such as I TS that do 
not have all six components. A component that is really “not tlicrc” is :unspecific in the 
pathname. When a pathname is converted to a string, nil and :unspecific both cause the 
component not to appear in die string. 

A component of a pathname can also be the special symbol :wild. 'ITiis is useful only when 
the patlmamc is being used with a directory primitive such as fs:directory-list (see page 598), 
where it means that this pathname component matches anything. 'I’hc printed representation of a 
patlmamc usually designates :wild with an asterisk; however, this is host-dependent 

What values are allowed for components of a pathname depends, in general, on the 
pathname's host. However, in order for patlinamcs to be usable in a system-independent way 
certain global conventions arc adhered to. These conventions are stronger for the type and version 
than for die other components, since die type and version arc actually understood by many 
programs, while the other components are usually just treated as somediing supplied by the user 
that only needs to be remembered. 

In general, programs can interpret the components of a pathname independent of the file 
system; and a certain minimum set of possible values of each component arc supported on all file 
systems, 'fhe same pathname component value may have very different representations when the 
pathname is made into a sU'ing, depending on the file system. I'his docs not affect programs that 
operate on the components. The user, when asked to type a pathname, always uses the system- 
dependent string representation. This is convenient for die user who moves between using the 
I.isp Machine on files stored on another host and making direct use of that host. However, when 
the mapping between string form and components is complicated, the components may not be 
obvious from what you type. 

The type is always a string, or one of the special symbols nil, runspecific, and :wild. 
Certain hosts impose a limit on the size of string allowed, often very small. Many programs that 
deal with files have an idea- of what type they want to use. For example. Lisp source programs 
arc usually "LISP", compiled Lisp programs are "QFASL", etc. However, dicse file type 
conventions arc host-specific, for the important reason that some hosts do not allow a SU'ing five 
characters long to be used as die type. Therefore, programs should use a canonical type rather 
than an actual string to specify their conventional default file types. Canonical types arc described 
below. 
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Kor ilic version, it is always legitimate to use a positive fixnum, or certain special symbols, 
nil, tunspecific, and :wild have been explained above. The other standardly allowed symbols are 
mewest and ;oldest. mewest refers to the largest version number that exists when reading a file, 
or tliat number plus one when writing a new file. :oldest refers to die smallest version number 
tliat exists. Some file systems may define other special version symbols, such as :installed for 
example, or may allow negative numbers. Some do not support versions at all. 'Ihcn a pathname 
may still contain any of the standard version components, but it docs hot matter what the value 
is. 


'I'hc device, directory, and name arc more system-dependent. 'I'hcsc can be strings (with host- 
dependent rules on allowed characters and length) or they can be siruciurcd. A structured 
component is a list of strings. I his is used for file system features such as hierarchical directories. 
The system is arranged so tliat programs do not need to know about structured components unless 
tlicy do host-dependent operations. Giving a string as a pathname component to a host that 
wants a structured value converts the string to the appropriate fonn. Giving a structured 
component to a host tliat docs not understand them converts it to a string by taking the first, 
clement and ignoring tlie rest. 

Some host file systems have features that do not fit into this pathname model. For instance, 
directories might be accessible as files, there might be complicated structure in the directories or 
names, or there might be relative directories, such as '<’ in Multics. These features appear in the 
parsing of strings into pathnames, which is one reason why the strings arc written in host- 
dependent syntax. Pathnames for hosts with these features are also likely to handle additional 
messages besides the common ones documented in this chapter, for tlic benefit of host-dependent 
programs that want to access those features. However, once your program depends on any such 
features, it will work only for certain file servers and not others: in general, it is a good idea to 
make your program work just as well no matter what file server is being used. 

24.2.1 Raw Components and Interchange Components 

On some host file systems it is conventional to use lower-case letters in file names, while in 
others upper case is customary, or possibly required. When pathname components are moved 
from pathnames of one file system to pathnames of another file system, it is useful to convert the 
case if necessary so that you get the right case convention for the latter file system as a default. 

This is especially useful when copying files from one file system to another. 

The Lisp Machine system defines two representations for each of several pathname 
components (the device, directory, name and type). There is the raw form, which is what 
actually appears in the filename on the host file system, and there is the interchange form, which 
may differ in alphabetic case from the raw form. The raw form is what is stored inside the 
pathname object itself, but programs nearly always operate on the interchange form. I’hc :name, 
:type, etc., operations return the interchange form, and the :new-name. etc., operations expect 
the interchange form. Additional operations :raw-name, etc., are provided for working with the 
raw components, but these are rarely needed. 

The interchange form is defined so that it is always customarily in upper case. If upper case 
is customary on the host file system, then the interchange form of a component is the same as 

the raw form. If lower case is customary on the host file system, as on Unix, then the 
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interchange form has ease inverted. More precisely, ;tn all-tippcr-c;isc component is changed to 
all-lowcr-casc, ;m till-Iowcr-ctisc component is chtmged to all-iippcr-case, and a mixed-case 
component is not changed. ( I'his is a one-to-one mapping). Thus, a Unix pathname with a name 
component of "foo" has an intcrchange-fomiat name of "FOO", and vice versa. 

1-or host file systems which record ettse when files arc created but ignore ease when comparing 
filenames, Uic interchange form is always upper ease. 


riic host component is not really a name, ;md ease is ttlways ignored in host names, so there 
is no need for two forms of host component. The version component docs not need them citlicr, 
because it is never a string. 


24.2.2 Pathname Component Operations 


:host 

tdevice 

tdirectory 

:naine 

:type 

;vers1on 

These return the components of the pathname. 


Operation on pathname 
Operation on pathname 
Operation on pathname 
Operation on pathname 
Operation on pathname 
Operation on pathname 
in interchange form. The returned values 


can be strings, special symbols, or lists of strings in the ease of structured components. 
The type is always a string or a symbol. The version is always a number or a symbol. 


:raw-device 
: raw-directory 
:raw-name 
:raw-type 

These return the components of the pathname, in raw form. 


Operation on pathname 
Operation on pathname 
Operation on pathname 
Operation on pathname 


;new-dev1ce dev 
:new-directory dir 
mew-name name 
mew-type type 
mew-version version 


Operation on pathname 
Operation on pathname 
Operation on pathname 
Operation on pathname 
Operation on pathname 


These return a new pathname that is the same as the pathname they are sent to except 
tliat the value of one of the components has been changed. I'he specified component 
value is inteiprcted as being in interchange form, which means its case may be converted. 
The :new-device, :new-directory and :new-name operations accept a string (or a 
special symbol) or a list dial is a structured name. If tlie host does not define structured 
components, and you specify a list, its first element is used, 

mew-raw-devico dev Operation on paXhndsnQ 

mew-raw-directory dir Opera/Zon on pathname 

mew-raw-name name Operation on psX\\na.et\Q 

mew-raw-type type 0/»cra//on on pathname 

These return a new pathname that is the same as the pathname they arc sent to except 
that tlie value of one of the components has been changed. 'The specified component 
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value is interpreted as raw. 

:new-suggested-naine name O/wn/Zo/; on pathname 

:n 0 w-suggested-d 1 rectory <//r 0/;fra//o/; pathname 

These difler from the :new-name and :new-directory operations in iliat the new 
patlinamc constructed has a name or directory based on the suggestion, but not necessarily 
identical to it. it tries, in a system-dependent manner, to adapt the suggested name or 
directory to tlic usual customs of tlic file system in use. 

T'or example, on a ’rOPS-20 system, these operations would convert name or dir to upper 
case, because while lower-case letters may appear in TOPS-20 pathnames, it is not 
customary to generate such pathnames by default. 

:new-pathnamd &rest opiions Opcraiion on pathname 

'This returns a new pathname that is the same as tlie pathname it is sent to except that 
the values of some of the components have been changed, opiions is a list of alternating 
keywords and values. The keywords all specify values of patlinamc components; they are 
:host, ;device, :directory, :name, :type, and :version. Alternatively, the keywords 
:raw-device, :raw-directory, :raw-name and :raw-type may be used to specify a 
component in raw form. 

'Two additional keywords, canonical-type and :original-type, allow the type field to be 
specified as a canonical type. Sec the following section for a description of canonical 
types. Also, the value specified for the keyword :type may be a canonical type symbol. 

If an invalid component is specified, it is replaced by some valid component so that a 
valid pathname can be returned. You can tell whether a component is valid by specifying 
it in mew-pathname and seeing whether that component of the resulting pathname 
matches what you specified. 

The operations :new-name, etc., arc equivalent to :new-pathname specifying only one 
component to be changed; in fact, that is how those operations arc implemented. 


24.2.3 Canonical Types 

Canonical types are a way of specifying a pathname type component using host-dependent 
conventions without making the program itself explicitly host dependent. For example, the 
function compile-file normally provides a default type of "LISP", but on VMS systems the 
default must be "LSP" instead, and on Unix systems it is "I". What compile-file actually does 
is to use a canonical type, the keyword :lisp, as the default. Tltis keyword is given a definition 
as a canonical type, which specifics what it maps into on various file systems. 

A single canonical type may have more than one mapping on a particular file system. For 
example, on TOPS-20 systems tlie canonical type :LISP maps into cither "LISP" or "LSP", One 
of the possibilities is marked as “preferred"; in this case, it is "LISP". ITie effect of this is that 
either FOO.LISP or FOO.LSP would be acceptable as having canonical type :lisp, but merging 
yields "LISP" as the type when defaulting from :lisp. 
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Note that the canonical type of a pathname is not a distinct component. It is another way of 
describing or specifying the type component. 

A canonical type must be defined before it is used. 

fs:d0f1ne-canon1cal-type Macro 

symbol siandard-mapping system-depeudenhmappings... 

Defines symbol a'S a canonical type, slandard-mapping is the actual type ctimponcnt that it 
maps into (a string), with exceptions as specified by sysicm-dependent-mappings. Kjich 
element of syslem-dependciil-mappings (that is, each addititmal argument) is a list of the 
fonn 

(system-type preferred-mapping other-mappings. . .) 
system-type is one of the system-type keywords the :system-type operation on a host 
object can return, such as :unix, :tops20, and :lispm (sec page 577). 'Ihc argument 
describes how to map this canonical type on that type of file system, preferred-map (a 
string) is the preferred mapping of the canonical type, and other-mappings arc additional 
strings that arc accepted as matching tlie canonical type. 

system-type may also be a list of system types. Then the argument applies to all of those 
types of file systems. 

All of the mapping strings arc in interchange form. 

For example, die canonical type :lisp is defined as follows: 
{fs;define-canonica1-type :lisp "LISP" 

(;unix "L" "LISP") 

{;vms "LSP") 

((:topsZ0 :tenex) "LISP" "LSP")) 

Other canonical types defined by the system include :qfasi, :text, :press, iqwabl, :babyl, 
:mail, :xmail, :init, rpatch-directory, :midas, :palx, :unfasl, :widths, :output, mac, 
tasm, doc, mss, tex, pl1 and clu. The suindard mapping for each is the symbol’s 
pname. 

Fo match a pathname against a canonical type, use the :canonical-type operation. 

: canon leal-type Opera//o/? o/i pathname 

Returns two values which describe whether and how this pathname’s type component 
matches any canonical type. 

If the type component is one of the possible mappings of some canonical type, the first 
value is diat canonical type (the symbol). 'Fhc second value is nil if the type component 
is die preferred mapping of the canonical type; otherwise it is the actual type component, 
in interchange form. 'Die second value is called the original type of the pathname. 

If the type component does not match a canonical type, the first , value is the type 
component in interchange form (a string), and the second value is nil. 
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This operation is useful in matching a patltnamc against a canonical type; the first value 
is eq to the canonical type if the pathname matches it. 'Ihc operation is also useful for 
transferring a type field from one file system to another while preserving canonical type; 
this is described below. 

A new patliname may also be constnictcd by specifying a canonical type. 

: new-canonical -type O/;cra//0H «//pathname 

canonical-type &optional original-type 

Returns a pathname different from tltis one in having a type component tliat matches 
canonical-type. 

If original-lyiw is a possible mapping for canonical-type on tliis patlinamc's host, then it is 
used as tlic type component. Otherwise, the preferred mapping for canonical-type is used. 
If original-type is not specified, it defaults to this pathname’s type component. If it is 
specified as nil, tlie preferred mapping of die canonical type is always used. If canonical- 
type is a string raUier dian an actual canonical type, it is used directly as the type 
component, and the original-type does not matter. 

'fhe :new-pathname operation accepts the keywords ;canonical-type and original-type. 
The ;new-canonical-type operation is equivalent to :new-pathname with those 
keywords. 

Suppose you wish to copy the file named old-pathname to a directory named target-directory- 
pathname, possibly on another host, while preserving the name, version and canonical type, ITiat 
is, if the original file has a name acceptable for a QFASL file, the new file should also. Here is 
how to compute the new pathname: 

(multiple-value-bind (canonical original) 

(send old-pathname :canonical-type) 

(send target-directory-pathname :new-pathname 
tname (send old-pathname :name) 

:version (send old-pathname :version) 

:canonical-type canonical 
:original-type original)) 

Suppose that old-pathname is OZ:<FOO>A.LISP.5, where OZ is a TOPS-20, and the target 
directory is on a VMS host. Then canonical is :lisp and original is "LISP". Since "LISP" is 
not an acceptable mapping for :lisp on a VMS system, the resulting padiname has as its type 
component the preferred mapping for :lisp on VMS, namely, "LSP". 

But if the target host is a Unix hosL the new file’s type is "LISP", since that is an 
acceptable (though not preferred) mapping for :lisp on Unix hosts. If you would rather that the 
preferred mapping always be used for the new file’s type, omit the :original-type argument to 
the :new-pathname operation. This would result in a type component of "L" in interchange 
form, or "I" in raw form, in the new file’s pathname. 

ITie function compile-file actually does something cleverer than using the canonical type as a 
default. Doing that, and opening the resulting pathname, would look only for tlie preferred 
mapping of the canonical type, compile-file actually tries to open each possible mapping, trying 
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the preferred mapping first. Here is how it docs so: 

:open-canon1cal-d0fault-typ0 OperaiUm on pathname 

canonical-type &rcst options 

If this pathname’s type component is non-nil, the pathname is simply opened, passing tlie 
options to tlic :open operation. If the type component is nil, each mapping of canonical- 
type is tried as a type component, in die order the mappings appear in the canonical type 
definition. If an open succeeds, a stream is returned. I’hc possibilities continue to be 
tried as long as fs:file-not-found errors happen; other errors arc not handled. If all die 
possibilities fail, a fs:file-not-found error is signaled for die caller, with a pathname that 
contains the preferred mapping as its type component. 

24.3 Defitulls and Merging 

When the user is asked to type in a pathname, it is of course unreasonable to require the 
user to type a complete pathname, containing all components. Instead there are defaults, so that 
components not specified by the user can be supplied automatically by the system. Each program 
that deals with pathnames typically has its own set of defaults. 

The system defines an object called a defaults alist. Functions are provided to create one, get 
the default pathname out of one, merge a pathname with one, and store a padinamc back into 
one. A defaults alist can remember more than one default pathname if defaults arc being kept 
separately for each host: this is controlled by the variable fs:*defaults-are-per-host'*. The main 
primitive for using defaults is the function fs:merge-pathname-defaults (see page 558). 

In place of a defaults alist, you may use just a pathname. Defaulting one pathname from 
another is useful for eases such as a program diat has an input file and an output file, and asks 
the user for the name of both, letting the unsupplied components of one name default from the 
other. Unspecified components of the output pathname come from the input pathname, except 
that the type should default not to the type of the input but to the appropriate default type for 
output from this program. 

The implementation of a defaults alist is an association list of host names and default 
padinames. 'Hie host name nil is special and holds the defaults for all hosts, when defaults are 
not per-host. 

'Hie merging operation takes as input a padiname, a defaults alist (or another pathname), a 
default type, and a default version, and returns a pathname. Basically, the missing components 
in the pathname arc filled in from the defaults alist. However, if a name is specified but the type 
or version is not, then the type or version is treated specially. 

Here are the merging rules in full detail. 

If no host is specified, die host is taken from the defaults. If the pathname explicitly specifies 
a host and docs not supply a device, then the die default file device for diat host is used. 

If the pathname specifics a device named DSK, that is replaced with the working device for 
the pathname’s host, and the directory defaults to die working directory for the host if it is not 
specified. See fs:set-host-working-directory, below. 


PS:<l..MAN>PArHNM.'rF.XT.99 


8-JUN-84 



1 isirMiichine Manual 


555 


I kfiiulls iiiid Merging 


Next, if the patlinamc docs not specify a host, device, directory, or name, Uiat component 
comes from die dcfiiults. 

If the value of fs:*always-merge-type-and-version* is non-nil, the type and version are 
merged just like die other components. 

If fs:*always-merge-type-and-version* is nil, as it normally is, the merging rules for the 
type and version arc more complicated and depend on whether the padinamc specifics a name. If 
the pathname doesn’t specify a name, then the type and version, if not provided, come from the 
defaults, just like the other components. However, if the pathname docs specify a name, dicn 
the type and vciNion come from the default-type and default-version arguments to merge- 
pathname-defaults. If those arguments were omitted, die value of fs:‘name-specified-default- 
type* (initially, :lisp) is used as die default type, and mewest is used as the default version. 

'I'lic reason for this is that the type and version “belong to" some other filename, and are 
dioughl to be unlikely to have anything to do with the new filename you arc typing in. 

fs:s 8 t-host-work 1 ng-d 1 rectory host pathname 

Sets the working device and working directory for host to those specified in pathname, 
host should be a host object or the name of a host, pathname may be a string or a 
pathname, ’fhe working device and working directory arc used for defaulting pathnames 
in which the device is specified as DSK. * 

The editor command Meta-X Set Working Directory provides a convenient interface to 
this function. 

llic following special variables are parts of the pathname interface that are relevant to 
defaults. 

fs:*d0faults-ar0-per-host* Variable 

This is a user customization option intended to be set by a user’s LISPM INIT file (see 
section 35.8, page 800). I’he default value is nil, which means that each program’s set of 
defaults contains only one default pathname. If you type in just a host name and a colon, 
the other components of the name default from the previous host, with appropriate 
translation to the new host’s pathname syntax. If fs:*defaults-are-per-host* is set to t, 
each program’s set of defaults maintains a separate default pathname for each host. If you 
type in just a host name and a colon, the last file that was referenced on that host is 
used. 

fs;*always-roerge-type-and-v 0 rs 1 on* Variable 

If this variable is non-nil, then the type and version are defaulted only from the 
pathname defaults just like the other components. 

fs;*name-spec 1 f ied-defauH-type* Variable 

If fs:*always-merge-type-and-version* is nil, then when a name is specified but not a 
type, the type defaults from an argument to the merging function. If that argument is 
not specified, this variable’s value is used. It may be a string or a canonical type 
keyword. The value is initially :lisp. 
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*d 0 fault-pathnam 0 -d 0 faults* 


Variable 


I'his is the dcfauli defaults alist: if the pathname primitives that need a set of deftiiilts arc 
not given one, tlicy use dds one. Most programs, however, should have their own 
defaults rather than using these. 

cl1 :*d 0 fault-pathnara 0 -d 0 fauTts* Variable 

The Common Lisp version of the default pathname defaults. 'Phe value of this variable is 
a pathname ratlier than an alist. Phis variable is magically (with a forwarding pointer) 
identified with a cell in die defaults-alist which die system really uses, so that setting this 
variable modifies the contents of the alist. 

fs: last-f ila-opanad Variable 

Phis is the pathname of die last file that was opened. Occasionally diis is useful as a 
default. Since some programs deal with files without notifying the user, you must not 
expect the user to know what die value of diis symbol is. Using diis symbol as a default 
may cause unfortunate surprises if you don’t announce it first, and so such use is 
discouraged. 

ITicse functions arc used to manipulate defaults alists directly. 

fs:mak 0 -pathnam 0 -d 0 fau 1 ts 

Creates a defaults alist initially containing no defaults. If you ask this empty set of 
defaults for its default pathname before anydiing has been stored into it you get the file 
FOO on the user’s home directory on die host he logged in to. 

fs; copy-pathnama-d 0 faults defaults 

Creates a defaults alist, initially a copy of defaults. 

fs'.dafault-pathnama &optional defaults host default-type default-version 

Phis is the primitive function for getting a default pathname out of a defaults alisL 
Specifying the optional arguments host, default-type, and default-version to be non-nil 
forces diose fields of the returned padiname to contain diose values. 

If fs:*defaults-are-per-host* is nil (its default value), this gets the one relevant default 
from the alist. If it is t, this gets the default for host if one is specified, otherwise for 
the host most recently used. 

If defaults is not specified, the default defaults are used. 

I’his function also has an additional optional argument internal-p, which is obsolete, 
fs:dafault-host defaults 

Returns die default host object specified by the defaults-alist defaults. This is the host 
used by pathname defaulting with the given defaults if no host is specified. 
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fs: set-default-pathname pathname &oplional defaults 

This is Uic primitive runclion for updating a set of defaults. It stores palhtuwie into 
defaults. If defaults is not specified, the default defitults are used. 

24.4 Pathname Functions 

1'his function obtains a patlTnamc from an object if that is possible. 


pathname object 

Converts object to a pathname and returns tliat, if possible. If object is a string or 
symbol, it is parsed. If object is a plausible stream, it is asked for its pathname with the 
:pathname operation. If object is a pathname, it is simply returned. Any other kind, of 
object causes an error. 

llicse functions arc what programs use to paisc and default file names that have been typed in or 

otherwise supplied by the user. 

parse-namestring thing &optional host defaults &key {start0) end junk-allowed 

Is tlic Common Lisp function for parsing file names. It is equivalent to fs:parse- 
pathname except in that it takes some keyword arguments where the other function takes 
all positional arguments. 

fs;parse-pathname thing &optional host defaults {start0) end junk-allowed 

This turns thing, which can be a paUiname, a string, a symbol, or a Maclisp-style name 
list, into a pathname. Most functions that arc advertised to take a pathname argument 
call fs;parse-pathname on it so that they can accept anything that can be turned into a 
pathname. If thing is itself a pathname, it is returned unchanged. 

If thing is a string, start and end arc interpreted as indices specifying a substring to parse. 
They are just like the second and third arguments to substring. The rest of thing is 
ignored, start and end are ignored if thing is not a string. 

If junk-allowed is non-nil, parsing stops without error if the syntax is invalid, and this 
function returns nil. The second value is then the index of the invalid character. If 
parsing is successful, the second value is the index of the place at which parsing was 
supposed to stop {end, or the end of thing). If junk-allowed is nil, invalid syntax signals 
an error. 

This function docs not do defaulting, even though it has an argument named defaults', it 
only docs parsing. TTie host and defaults arguments are there because in order to parse a 
string into a pathname, it is necessary to know what host it is for so that it can be parsed 
with the file name syntax peculiar to that host. If thing does not contain a manifest host 
name, then if host is non-nil, it is the host name to use, as a string. If thing is a string, 
a manifest host name may be at the beginning or the end, and consists of the name of a 
host followed by a colon. If host is nil then the host name is obtained from the default 
pathname in defaults. If defaults is not supplied, the default defaults (’default- 
pathname-defaults*) are used. 


PS:<L.M AN>PATHNM .TEXT.99 


8 -JUN -84 



Piilhiiiimc l-'iinctions 


558 


l isp Machine Manual 


Note iliat if has! is specified. And ihiug contains a host name, an error is signaled if tlicy 
arc not the Siimc host. 

fs: pathname-parse-error (fs:pathname-error error) Condition 

I'his condition is signaled when fs:parse-pathname finds a syntax error in tlic string it is 
given. 

fs:parse-pathname sets up a nonlocal proceed type mew-pathname for this condition. 
The proceed type expects one argument, a pathname, which is returned from fs.’parse- 
pathname. 

fs :merge-pathname-defaults pathname &optional defaults default-type default-version 

f'ills in unspecified components of pathname from the defaults and returns a new 
patliname. 'Hiis is tlie function tliat most programs should call to process a file name 
supplied by the user, pathname can be a pathname, a string, a symbol, or a Maclisp 
namelist. The returned value is always a pathname. The merging rules are dtKumcnted 
on page 554. 

If defaults is a pathname, rather than a defaults alist, then the defaults are taken from its 
components. 'I’his is how you merge two pathnames. (In Maclisp tJiat operation is called 
mergef.) 

defaults defaults to the value of ‘default-pathname-defaults* if unsupplied, default-type 
defaults to the value of fs:*name-specified-default-type*. default-version defaults to 
mewest. 

merge-pathnames pathname &optional defaults (default-version :nev/es\) 

Is tlte Common Lisp function for pathname defaulting. It docs only some of the things 
that fs:merge-pathname-defaults docs. It merges defaults from defaults (which defaults 
to die value of ‘default-pathname-defaults*) into pathname to get a new pathname, 
which is returned, pathname can be a string (or symbol); then it is parsed and the result 
is defaulted, default-version is used as the version when pathname has a name but no 
version. 

fs :merge-and-S0t-pathnaroe-d0fau1ts pathname &optional defaults default-type 
default-version 

This is the same as fsrmerge-pathname-defaults except tliat after it is done the defaults- 
list defaults is modified so that the merged pathname is tlie new default. Tliis is handy 
for programs that have sticky defaults, which means that the default for each command is 
tlic last filename used. (If defaults is a pathname rather than a defaults alist, then no 
storing back is done.) The optional arguments default the same way as in fs:merge- 
path name - defaults. 
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riicsc functions convert a patlinamc into a nanicstring for all or some of the pathname’s 
components. 

tiamestring pathmme 

Returns a string containing tlic printed fonn of pathname, as you would type it in. This 
uses the :string-for-printing operation. 

file-namestring pathname 

Returns a string showing just the name, type and version of pathname. 'I'his uses the 
:string-for-dired operation. 

d1rectory-namestr1ng pathname 

Returns a string showing just die device and directory of pathname. I'his uses the 
:string-for-directory operation. 

enough-naroestring pathname &optional defaults 

Returns a string showing just the components of pathname which would not be obtained 
by defaulting from defaults. This is the shortest string that would suffice to specify 
pathname, given those defaults. It is made by using the :string-for-printing operation on 
a modified pathname. 

Ihis function yields a patliname given its components. 

make-pathname &key (defaults^) host device raw-device directory raw-directory name 
raw-name type raw-type version canonical-type original-type 
Returns a pathname whose components are as specified. 

If defaults is a pathname or a dcfaults-alist, any components not explicitly specified default 
from it. If defaults is t (which is the default), then unspecified components default to nil, 
except for the host (since every patliname must have a specific host), which defaults based 
on ‘default-pathname-defaults*. 

These functions give the components of a pathname. 

pathname-host pathname 

Returns the host component of pathname. 

pathname-device pathname 
pathname-directory pathname 
pathname-name pathname 
pathname-type pathname 
pathname-version pathname 

Likewise, for the other components 
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These functions return useful infomiaiion. 

fs:user-homed 1 r &optional host rcsei-p (Hie/ user-id) force-p 
user-homedlr-pathname &optional /»«/ reset-p (/vseruser-id) force-p 

Returns the patlinamc of tlic user ’s home directory on host. 'I'hese default to the logged 
in user and the host logged in to. Home directory is a somewhat system-dependent 
concept, but from tlie point of view of the l.isp Machine it is the directory where the 
user keeps personal files such as init files and mail. 

This function returns a pathname without any name, type, or version component (tht)se 
components arc all nil). 

If resehp is specified non-nil, tile machine tlie user is logged in to is changed to be host. 

The synonym user-homedir-pathname is from Common Lisp. 

Init-fHa-pathname program-mime &optional host 

Returns tlte patlmame of the logged-in user’s init file for the program program-name, on 
the host, which defaults to the host tlie user logged in to.. Programs tliat load init files 
containing user customizations call this function to find where to look for the file, so that 
tlicy need not know the separate init file name conventions of each host operating system. 
The program-name "LISPM" is used by the login function. 

These functions arc useful for poking around. 

fs’.dascribe-pathname pathname 

If pathname is a patlinamc object, this describes it, showing you its properties (if any) 
and information about files with that name that have been loaded into the machine. If 
pathname is a string, this describes all interned patlinamcs tliat match that string, ignoring 
components not specified in tlie string. One tiling this is useful for is finding the directory 
of a file whose name you remember. Giving describe (see page 791) a pathname object 
invokes this function. 

fs:pathname-pHst pathname 

Parses and defaults pathname, then returns the list of properties of that pathname. 

fs:*pathname-hash-table* Variable 

This is the hash table in which pathname objects arc interned. You can find all 
patlinamcs ever constructed by applying the function maphash to this hash table. 
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24.5 Generic PiUhiiames 

A generic pathname sUinds for a whole family of files. The property list of a generic 
pathname is used to remember information about the family, some of which (such as Uie package) 
comes from tlie line (see section 25.5, page 594) of a source file in the family. Several types 

of files with that name, in tliat directory, belong together. Ibey are different members of the 
same family: for example, they may be source code and compiled code. However, there may be 
several other types of files that form a logically distinct group even though they have this same 
name; TEXT and PRESS for example. I’he exact mapping is done on a per host basis since it 
can sometimes be affected by liost naming conventions. 

The generic pathname of patlmame p usually has the same host, device, directory, and name 
as p docs. However, it has a vereion of runspecific. The type of the generic patlmame is 
obtained by sending a rgeneric-base-type O’/JC-o/p message to the host of p. TTic default 
response to tliis message is to return tlic asswiated type from fs:*generic-base-type-alist* if 
tlicrc is one, else type-of-p. Both the argument and tlic value arc cither strings, in interchange, 
form, or canonical type symbols. 

However, tlic I'fS file system presents special problems. One cannot distinguish multiple 
generic base types in this same way since the type component docs not exist as such; it is derived 
frorh the second filename, which unfortunately is also sometimes used as a version number. ITius, 
on ITS, the type of a generic padmamc is always :unspecific if there is any association for tlie 
type of the pathname on fs:*generic-base-type-alist*. 

Since generic pathnames arc primarily useful for storing properties, it is important that they 
be as standardized and conceptualized as possible. For this reason, generic pathnames are defined 
to be backtranslatcd, i.e. the generic patlmame of a pathname that is (or could be) the result of a 
logical host translation has the host and directory of the logical pathname. For example, the 
generic pathname of OZ:<L.WINDOW>;STREAM LISP would be SYS:WINDOW:STREAM U U if 
OZ is the system host. 

All version numbers of a particular pathname share the same identical generic pathname. If 
the values of particular properties have changed between versions, it is possible for confusion to 
result. One way to deal with this problem is to have the property be a list associating version 
number with the actual desired property. Then it is relatively easy to determine which versions 
have which values for the property in question and select one appropriately. But in the 
applications for which generic pathnames arc typically used, this is not necessary. 

ITic :generic-path name operation on a pathname returns its corresponding generic pathname. 
Sec page 563. The :source-pathname operation on a pathname returns the actual or probable 
pathname of the corresponding source file (with :newest as the version). See page 563. 

fs:*genep1c-bas0-type-al1st* Variable 

This is an association list of the file types and the type of the generic pathname used for 
the group of which that file type is a part. Constructing a generic pathname replaces the 
file type with the association from this lisL if there is one (except that ITS hosts always 
replace with runspecific). File types not in this list are really part of the name in some 
sense. The initial list is 


PS:<1 ..MAN5PATHNM.TEXT.99 


8-JUN-84 



(icncric I’alhnamcs 562 l.isp Machine Manual 


((:text . :text) ("DOC" . :text) 

(:press . :text) ("XGP" . :text) 

(:11sp . ;unspecific) (:qfasl . lunspecific) 

(nil . :unspecific)) 

The ass(K:iation of :lisp and :unspecific is iinforlunatcly made necessary by Uie problems 
of ffS mentioned previously. Ibis way makes the generic patlinames of logically mapped 
LISP files identical no matter whether tlte logical host is mapped to an I TS host or not. 

The first enti 7 in the list with a particular edr is die entry for the type that source files 
have. Note how tJtc first element whose edr is :unspecific is the one for :lisp. 'ITiis is 
how the ;source-pathname operation knows what to do, by default. 

Some users may need to add to this list. 

The system records certain properties on generic pathnames automatically. 

:warnings 'fhis property is used to record compilation and other warnings for the file. 

:definitions This property records all the functions and other things defined in tlic file. The 
value has one element for each package into which the file has been loaded; the 
element’s car is the package itself and the edr is a list of definitions made. 

Each definition is a cons whose car is the symbol or ftinction spec defined and 
whose edr is the type of definition (usually one of the symbols defun, defvar, 
defflavor and defstruct). 

isystems I'his property’s value is a list of the names of all the systems (defined with 
defsystem, see page 660) of which this is a source file. 

:file-id-package-alist 

This property records what version of the file was most recently loaded. In case 
the file has been loaded into more than one package, as is sometimes necessary, 
the loaded version is remembered for each package separately. 'Fins is how 
make-system tells whether a file needs to be reloaded. The value is a list with 
an element for each package that tlie file has been loaded into; the elements look 
like 

(package file-information) 

package is the package object itself; file-information is the value returned by tlie 
:info operation on a file stream, and is usually a cons whose car is the truename 
(a pathname) and whose edr is the file creation date (a universal time number). 

Some additional properties are put on the generic pathname by reading the attribute list of 
the file (sec page 597). It is not completely clear that this is the right place to store these 
properties, so it may change in the ftiuirc. Any property name can appear in the attributes list 
and get onto the generic pathname; the standard ones arc described in section 25.5, page 594. 
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24.6 Pathname Operations 

I’his section dixrumcnts the operations a user may send to a pathname object. Pathnames 
handle some additional operations tliat are only intended to be sent by the file system itself, and 
therefore are not d()cumented here. Someone who wants to add a new host to Uie system would 
need to understand diosc internal operations. 

'ITic operations on pathnames that actually operate on files are documented in section 25.4, 
page 592. Certain pathname flavors, for specific kinds of hosts, allow additional special purpose 
operations. These are documented in section 24.7, page 568 in the section on the specific host 
type. 

: generic-pathname o/; pathname 

Keturns the generic pathname for tlie family of files of which tliis pathname is a member. 
See section 24.5, page 561 for dtKumciitation on generic patlmames. 

: source-pathname Operation on 

Returns the patliname for the source file in the family of files to which this pathname 
belongs. The returned pathname has :newest as its version. If the file has been loaded 
in some fashion into the Lisp environment, then the pathname type is that which the user 
actually used. Otherwise, the conventional file type for source files is determined from the 
generic pathname. 

: primary-device Oprraho/jo/i pathname 

Returns the default device name for the pathname’s host. This is used in generating the 
initial default pathname for a host. 

Operations dealing with wildcards. 

The character • in a namestring is a wildcard. It means that the pathname is a really a 
pattern which specifies a set of possible filenames rather than a single filename. ITic matches any 
sequence of characters within a single component of the name. Thus, the component FOO* 
would match FOO, FOOBAR, FOOT, or any other component starting with FOO. 

Any component of a pathname can contain wildcards except the host; wild hosts are not 
allowed because a known host is required in order to know what flavor the pathname should be. 
If a pathname component is written in the namestring as just •, the actual component of the 
pathname instance is the keyword :wild. Components which contain wildcards but are not simply 
a single wildcard are represented in ways subject to change. 

Pathnames whose components contain wildcards are called wild pathnames. Wild pathnames 
useful in functions such as delete-file for requesting the deletion of many files at once. Less 
obviously but more fundamentally, wild pathnames arc required for most use of the function 
fs:directory-list; an entire directory’s contents are obtained by specifying a pathname whose 
name, type and version components are :wild. 


PS:<L.MAN>PATHNM.TEXT.99 


8-JUN-84 



564 


l isp Machine Manual 


l*atlinanie Operations 


:wild-p O/vra/wH 0 /;pathname 

Returns non-nil if this pathname contains any sort of wildcards. If the value is not nil, it 
is a keyword, one of device, :directory, :name, :type and :version, and it identifies the 
‘first’ component which is wild. 

:d 0 v 1 c 0 -w 1 ld-p pathname 

t if tliis patlmame’s device contains any sort of wildcards. 


:directopy-wnd-p 
:name-wlld-p 
:typ 0 -wild-p 
:verslon-wlld-p 

Similar, for tlie other components tliat can be wild. 


Operation on pathname 
Operation on pathname 
Operation on pathname 
Operation on pathname 
(The host cannot ever be wild.) 


: pathname-match Operation on pathname 

candidate-pathname &optiona1 [inatch-host-p t) 

Returns t if candidate-pathname matches the pathname on which the operation is 
invoked (called, in this context, die pattern pathname). If die pattern pathname contains 
no wildcards, the pathnames match only if they are identical. ’I’his operation is intended 
in cases where wildcards arc expected. 

Wildcard matching is done individually by component; the operation returns t only if 
each component matches. Within each component, an occurrcncs of * in pattern 
padmame’s component can match any sequence of characters in candidate-pathname's 
component. Other characters, except for host-specific wildcards, must match exactly. :wild 
as a component of die pattern pathname matches any component dtat candidate-pathname 
may have. 


Note that if a component of the pattern padiname is nil, candidate-pathname's component 
must be nil also to match it. Most user programs that read pathnames and use them as 
patterns default unspecified components to :wild first. 

Examples: 
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(defvar pattern) 

(defun test (str) 

(send pattern 

:pathname-match 
(parse-namestring str))) 

(setq pattern 

(parse-namestring "OZ:*:<F*0>*.TEXT.♦")) 

(test "0Z:<F00>A.TEXT") => t 
(test "0Z;<F0>HAHA.TEXT.3") => t 
(test "OZ:<FPPO>HAHA.TEXT.*") => t 
(test "OZ:<FOX>LOSE.TEXT") => nil 

(setq pattern 

(parse-namestring "OZ:♦:<*>A.TEXT*.5”)j 

(test "0Z:<F00>A.TEXT.5") => t 
(test "0Z:<F00>A.TEXTTTT.5") => t 
(test "0Z:<F00>A.TEXT") => nil 

If match-hosi-p is nil, then the host components of the two pathnames are not tested. 
The result then depends only oh tlie other components. 

: transi ate-wl 1 d-pathname \ Operation on pathname 

target-pattern starting-data &optional reversible 
Returns a patliname corresponding to starting-data under the mapping defined by the wild 
patlinames source-pattern, which is the pathname this operation is invoked on, and target- 
pattern, the argument. It is expected that starting-data would match the source pattern 
under the :pathname-match operation. 

:translate-wild-pathname is used by functions such as copy-file which use one wild 
pathname to specify a set of files and a second wild pathname to specify a corresponding 
filename for each file in the set. The first wild pathname would be used as the source- 
pattern and tire second, specifying the name to copy each file to, would be passed as the 
target-pattern pathname. 

Each component of the result is computed individually from the corresponding 
components of starting-data and the pattern pathnames, using the following rules: 

1) If target-pattern's component is ;wild, then the result component is taken from 
starting-data. 

2) Otherwise, each non-wild character in target-pattern's component is taken literally into 
the result. Each wild character in target-pat tern's component is paired with a wild 
character in source-pattern's component, and thereby with the portion of starting- 
data's component which that matched. This portion of starting-data appears in the 
result in place of the wild target character. 
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Hxamplc: 

(setq source (fs:parse-pathname "OZ:PS:<F00>A*B».♦.*")) 

(setq target (fs:parse-pathname "OZ;SS:<*>*LPSE*.*8.♦")) 

(send source :translate-wiId-pathname target 

(fsrparse-pathname "OZ:PS:<F00>ALIBI.LISP.3")) 

=> //;r/w//;/w//;rOZ:SS:<FOO>LILOSEI.LISPB.3 

It is easiest to understand the mapping as being done in interchange case; die interchange 
components of die arguments arc used and the results specify die interchange components 
of die value. 

The type component is slightly special; if the target-pat tern type is ;wild, the canonical 
type of starting-data is taken and dicn interpreted according to the mappings of the target 
host. Example: 

(setq source (fs:parse-pathname "OZ:PS:<F00>A*.*.*")) 

(setq target (fs:parse-pathname "U://usr//foo//b*.♦")) 

(send source :translate-wiId-pathname target 

(fs:parse-pathname "OZ:PS:<F00>ALL.LISP")) 

=> thepa^hnameU:/\JS^/foo/b^'i ,1 

If reversible is non-nil, rule 1 is not used; rule 2 controls all mapping. This mode is used 
by logical padiname translation. It makes a difference when the target pattern component 
is :wiid and die source pattern component contains wildcards but is not simply :wild. For 
example, with source and target pattern components BIG* and *, and starting data 
BIGGER, the result is ordinarily BIGGER by rule 1, but with reversible translation the 
result is GER. 

Operations to get a path name string out of a pathname object: 

:string-for-pp1nt1ng Operat/on oh pathname 

Returns a string tiiat is the printed representation of the path name. This is the same as 
what you get if you princ the pathname or take string of it. 

:string-for-whol Ine length Opera/Zon oh pathname 

Returns a string like the :string-for-printing, but designed to fit in length characters. 
length is a suggestion: the actual returned string may be shorter or longer than that. 
However, the who-line updater truncates the value to that length if it is longer. 

:str1ng-for-ed1tor Op<?ra//oH oh pathname 

Returns a string that is die pathname with its components rearranged so that the name is 
first. The editor uses this form to name its buffers. 
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:str1ng-for-d1r0d Opera lion on peAhname 

Returns a siring to be used by the directory editor. The siring contains only the name, 
type, and version. 

:str1ng-for-d1rectttry Operation on pathname 

Returns a string th:it contains only the device and directory of the pathname. It identifies 
one directory among all directories on the host, 

!StPlng-for-host Operation on pathname 

Returns a siring that is die pathname the way the host file system likes to see it. 

Operations to move around through a hierarchy of directories: 

: pathname-as-dl rectory Operation on pathname 

Assuming that the file described by tlic patlinamc is a directory, return another patliname 
specifying that as a directory. Thus, if sent to a pathname OZ:<RMS>FOO.DlRECTORY, 
it would return the patlinamc OZ:<RMS.FOO>. The name, type and version of the 
returned pathname arc lunspecific. 

:d1rectory-pathnaine-as-f lie Operation on pathname 

lliis is die inverse of the preceding operation. It returns a pathname specifying as a file 
the directory of the original patlinamc. 'ITie name, type and version of the original 
pathname arc ignored. 


The special symbol :root can be used as the directory component of a pathname on file 
systems that have a root directory. 

Operations to manipulate the property list of a pathname: 


:get property'-name &optional default-value 
: g 0 11 list-of-property-names 
:putprop value property-name 
:remprop property-name 
: pi1st 


Operation on pathname 
Operation on pathname 
Operation on pathname 
Operation on pathname 
Operation on pathname 


These manipulate the pathname’s property list, and arc used if you call the property list 
functions of the same names (see page 114) giving the pathname as the first argument 
Please read the paragraph on page 546 explaining the care you must take in using 
property lists of pathnames. 
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24.7 Host File Systems Supported 

I'his section lists the host file systems supported, gives an example of the patlinamc syntax for 
each system, and discusses any special idiosyncracics. More host types may be added in the 
future. 

24.7.1 ITS 

An 1 rS pathname looks like "hosi: device: dir; name type-or-verskm". The primary device 
is DSK; but other devices such as ML:, ARC:, DVR:, or PTR: may be used. 

n s docs not exactly fit tlic virtual file system model, in that a file name has two components 
(b'Nl and FN2) rather than tlirce (name, type, and version). Consequently to map any virtual 
pathname into an I TS filename, it is necessary to decide whether the FN2 is the type or the 
version. The rule is that usually the type goes in the FN2 and the version is ignored; however, 
certain types (LISP and TEXT) arc ignored and instead the version goes in the FN2. Also if the 
type is lunspecific the FN2 is tlie version. 

Given an ITS filename, it is converted into a pathname by making the FN2 the version if it 
is '<’, *>’, or a number. Otherwise the FN2 becomes the type. ITS pathnames allow the special 
version symbols :oldest and :newest, which correspond to *<’ and *>’ respectively. 

In every ITS pathname either the version or ^e type is :unspecific or nil; sometimes both 
are. When you create a new ITS pathname, if you specify only the version or only the type, the 
one not specified becomes :unspecific. If both are specified, tlie version is :unspecific unless the 
type is a normally-ignored type (such as LISP) in which case the version is :newest and the type 
is :unspecific so that numeric FN2’s are found. 

Each component of an ITS pathname is mapped to upper case and truncated to six characters. 

Special characters (space, colon, and semicolon) in a component of an ITS pathname can be 
quoted by prefixing them with right horseshoe (d) or equivalence sign (s). Right horseshoe is the 
same character code in the Lisp Machine character set as control-Q in tlie ITS character set 

An ITS pathname can have a structured name, which is a list of two strings, the FNl and 
the FN2. In this case lliere is neither a type nor a version. 

An ITS pathname with an FN2 but no FNl (i.e. a type and/or version but no name) is 
represented with the placeholder FNl because ITS pathname syntax provides no way to write 
an FN2 without an FNl before it 

Ihc ITS init file naming convention is "homedir; user program". 

fs: *1ts-un1nteresting-types* Variable 

The ITS file system does not have separate file types and version numbers; both 
components arc stored in the “FN2’'. This variable is a list of the file types that are “not 
important"; files with these types use tlie FN2 for a version number. Files with other 
types use tlie FN2 for the type and do not have a version number. 'Ihc initial list is 
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("LISP" "TEXT" nil runspecific) 

Some users may need to add to this list. 

• fnl Operation on Ws-pathnavne 

;fn2 (»; its-pathname 

’Hiesc two operations return a string that is the FNl or FN2 host-dependent component 
of the pathname. 

:type-and-vePs1on O/vra/w/; oh pathname 

: new-typ8-and-v0PSlon new-type new-version Operation on peAhname 

I'hcse two operations provide a way of pretending tliat I TS patlinames can have both a 
type and a version. I'hcy use the first three characters of the FN2 to store a type and the 
last three to store a version number. 

On an ITS-pathname, :type-and-version returns the type and version tlius extracted (not 
the same as the type and version of the pathname). :new-type-and-version returns a 
new pathname constructed from die specified new type and new version. 

On any other type of patlinamc, these operations simply return or set both the type 
component and the version component. 

24,7.2 TOPS-20 (Twenex), Tenex, and VMS. 

A pathname on TOPS-20 (better known as Twenex) looks like 
host : device : <directory> name. type. version 
The primary device is PS:. 

TOPS-20 pathnames are mapped to upper case. Special characters (including lower-case 
letters) arc quoted with the circle-cross (») character, which has the same character code in the 
Lisp Machine character set as Control-V, tlie standard Twenex quoting character, in the ASCII 
character set 

If you specify a period after the name, but nothing after that, then the type is :unspecific, 
which translates into an empty extensiem on the TOPS-20 system. If you omit the period, you 
have allowed the type to be defaulted. 

TOPS-20 pathnames allow the special version symbols :oldest and mewest. In the string 
form of a pathname, these are expressed as ‘.-2’, and as an omitted version. 

The directory component of a TOPS-20 pathname may be structured. The directory 
<FOO.BAR> is represented as the list ("FCXD" "BAR"). 

The characters ♦ and % are wildcards tliat match any sequence of characters and any single 
character (within one pathname component), respectively. To specify a filename that actually 
contains a * or % character, quote the character with «. When a component is specified with just 
a single *, the symbol :wild appears in the pathname object. 
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The 'l'OI’S-20 inil file ntiming convention is "<user>pwgram.\H\V'. 

When there is an attempt to display a TOI’S-20 file name in tlic who-line and there isn't 
enough room to show die entire name, die name is truncated and followed by a center-dot 
chiiiacter to indicate dial dierc is more to die name than can be displayed. 

Tencx pathiiamcs are almost the same as 'l'OPS-20 padinames, except thiit die version is 
prccecdcd by a semi-colon instead of a period, die defiiult device is DSK instead of PS, and the 
quoting requirements are slightly different. 

VMS padinames are basically like rOPS-20 padinames, with a few complexities. I'lie primary 
device is USRD$. 

First of all, only alphanumeric characters arc allowed in filenames (though $ and iindcrecorc 
can appear in device names). 


Secondly, a version number is preceded by rather dian by 


Thirdly, file types (called “extensions” in VMS tenninology) are limited to dircc characters. 
Each of die system's canonical types has a special mapping for VMS padinames, which is three 
characters long: 


:lisp -♦ LSP 
:press PRS 
:qwabl -» QWB 
: init INI 


:text TXT 
:widths ■* WID 
:baby1 ■+ BAB 
:unfasl ■* UNF 


:qfas1 -» QFS :fflidas -♦ MID 

:patch-directory -♦ PDR 
:mail •* MAI :xinail XML 

:output OUT 


24.7.3 Unix and Multics Pathnames 

A Unix pathname is a sequence of directory or file names separated by slashes. The last 
name is die filename; preceding ones are directory names (but directories are files anyway). There 
are no devices or versions. Alphabetic case is significant in Unix pathnames, no case conversion 
is nonnally done, and lower case is the default. Therefore, components of solid upper or lower 
case are inverted in case when going between interchange form and raw form. (What the user 
types in a padiname string is die raw form.) 

Unix allows you to specify a padiname reladve to your default directory by using just a 
filename, or starting with die first subdirectory name; you can specify it starting from the root 
directory by sunting with a slash. In addition, you can start with as a directory name one or 
more Umes, to refer upward in the hierarchy from the default directory. 

Unix pathnames on the l.isp Machine provide all these features too, but the canonicalization 
to a simple descending list of directory names starting from the root is done on the Lisp Machine 
itself when you merge the specified padiname with die defaults. 

If a pathname string starts with a slash, die pathname object diat results from parsing it is 
called “absolute”. Otherwise the pathname object is called “relative”. 
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In an absolute pathname object, the directory component is either a symbol (nil. :unspecific 
or :root). a string, or a list ol’ strings. A single string is used when there is only one level of 
directory in die pathname. 

A relative pathname has a directory that is a list of the symbol :relative followed by some 
strings. When the pathname is merged with defaults, the strings in the list arc appended to tlie 
strings in the default directory. The result of merging is always an absolute pathname. 

In a relative patlmamc's string fonn, the string can be used as a directory name. It is 
translated to the symbol :up when the string is parsed. That symbol is processed when the 
relative pathname is merged with the defaults. 


Restrictions on the length of Unix pathnames require abbreviations for the sumdard Zeutlisp 
pathname types, Just as for VMS. On Unix die preferred mappings of all canonical types are one 
or two characters long. We give here the mappings in raw fonn; they arc actually specified in 
interchange form. 


: 1 isp -» 1 
:press ^ pr 
:qwabl -» qw 
:init in 


:text -» tx 
iwidths -♦ wd 
:babyl -♦ bb 
:unfasl uf 


:qfasl ■+ qf :midas ■* md 
:patch-directory -» pd 
:niail -♦ ma :xmail -» xm 

;output -♦ ot 


The Multics file system is much like the Unix one; there are absolute and rcladvc pathnames, 
absolute ones start with a directory delimiter, and there are no devices or versions. Alphabetic 
ease is significant. 


There arc differences in "details. Directory names are terminated, and absolute padinamcs 
begun, with the character '>'. The containing directory is referred to by the character *<’, which 
is complete in itself. It does not require a delimiter. Thus, «FOO>BAR refers to subdirectory 
FOO, file BAR in the superdirectory of die supcrdircctory of the default directory. 

Tlie limits on filename sizes are very large, so the system canonical types all use their 
standard mappings. Since the mappings are specified as upper case, and then interpreted as being 
in interchange form, the actual file names on Multics contain lower case. 


24.7.4 Lisp Machine File Systems 

ITicre arc two file systems that run in the MIT Lisp Machine system. They have different 
pathname syntax. Both can be accessed either remotely like any other file server, or locally. 

The Local-File system uses host name LM for the machine you are on. A Local-File system 
on another machine can be accessed using the name of that machine as a host name, provided 
that machine is known as a file server. 

The remainder of the pathname for the Local-File system looks like "directory, 
name.iypeit version”, 'fhere is no restriction on die length of names; letters are converted to 
upper case. Subdirectories are allowed and are specified by putting periods between the directory 
components, as in RMS.SUBDIR;. 
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The rOPS-20 pallinamc syntax is also accepted. In addition, if the flag fs:*lmfs-use- 
twenex-syntax* is non-nil, l.ocal-l’ilc pathnames print out using TOPS-20 syntax. Note that 
since die printed representation of a pathname is cached, changing this flag’s value does not 
change the printing of pathnames with existing representations. 

flic l.ocaM-ile system on die filecomputer at MU' has the host name FS. 

file I.Mf'll.H system is primarily for use as a file server, unless you have 512k of memory. 
At MIT it runs on the filecomputer and is accessed remotely with host name FC. 

I'he remainder of an l.MFll.F. pathname looks like "directory, mine type# version". 
However, die directory and name can be composed of any number of subnames, separated by 
backslashes, ’fhis is how subdirectories arc specified. FOO;BAR\X refers to die same file as 
FOO\BAR;X, but the two ways of specifying die file have diflerent consequences in defaulting, 
getting directory listings, etc. 

Case is significant in I.MHITE pathnames: however, when you open a file, the LMFILE 
system ignores die ease when it matches your pathname against the existing files. As a result, the 
case you use matters when you create or rename a file, and appears in directory listings, but it is 
ignored when you refer to an existing file, and you cannot have two files whose names differ only 
in ease. When components arc accessed in interchange form, they are always converted to upper 
case. 

24.7.5 Logical Pathnames 

There is another kind of padinamc that doesn’t correspond to any particular file server. It is 
called a logical pathname, and its host is called a logical host. Every logical pathname can be 
translated into a corresponding physical padiname because each logical host records 9 
corresponding actual (“physical”) host and rules for translating the other components of the 
padiname. 

I'he reason for having logical pathnames is to make it easy to keep bodies of software on 
more than one file system. An important example is the body of software that constitutes the 
Lisp Machine system. Every site has a copy of all of the sources of the programs that are loaded 
into die initial l.isp environment. Some sites may store die sources on an H'S file system, while 
others may store them on a ’rOPS-20. However, system software (including make-system) wishes 
to be able to find a particular file independent of the name of the host a particular site stores it 
on, or even the kind of host it is. This is done by means of the logical host SYS: all pathnames 
for system files arc actually logical pathnames with host SYS. At each site, SYS is defined as a 
logical host, but translations are different at each site. For example, at Mff the source files are 
stored on the rOPS-20 system named OZ, so Mn”s site file says that SYS should translate to the 
host OZ. 

F.ach logical host, such as SYS, has a list of translations, each of which says how to map 
certain pathnames for that host into pathnames for the corresponding physical host. To translate a 
logical padinamc, the system tests each of the logical host’s translations, in sequence, to see if it 
is applicable. (If none is applicable, an error is signaled.) A translation consists of a pair of 
padinames or namestrings, typically containing wildcards. Unspecified components in them default 
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to :wild. 'I'he /w/»-patlinaiTic of the translation is used to match against the pathname to be 
translated; if it matches, the corresponding /o-pathname is used to construct the translation, filling 
in its wild fields from the pathname being translated as in tlie :translate-wild-pathname 
operation (page 565). , , 

Most commonly the translations contain pathnames tliat have only directories speeified, 
everything else wild. Then the other components are unchanged by translation. 

If the files accessed through die logical host are moved, the translations can be changed so 
that the Siime logical pathnames refer to the same files on tlieir new physical host via physical 
pathnames changed to fit the restrictions and the conventions of tlie new physical host. 

Ivach translation is specified as a list of two strings. I'he strings are parsed into pathnames 
and any unspecified components arc defaulted to :wild. The first string of the pair is the source 
pattern; it is parsed with logical pathname syntax, fhe second string is the target pattern, and it 
is parsed with the patlinamc syntax for tlie specified physical host. 

I'or example, suppose tliat logical host FOO maps to physical host BAR, a lops-20, and has 
the following list of translations: 

(("BACK;" "PS:<F00.BACK>") 

("FRONT;* QFASL" "SS:<F00.QFASL>*.QFASL") 

("FRONT;" "PS:<F00.FR0NT>")) 

Tlicn all pathnames with host FOO and directory BACK translate to host BAR, device PS and 
directory <FOO.BACK> with name, type and version unchanged. All pathnames with host FOO, 
directory FRONT and type QFASL translate to host BAR, device SS, directory <FOO.QFASL> 
and type QFASL, with name and version unchanged. All other pathnames with host FOO and 
directory FRONT map to host BAR, device PS and directory <FOO.FRONT>, with name, type 
and version unchanged. Note that the first translation whose pattern matches a given patliname is 
the one that is used. 

Another site might define FCMD’s to map to a Unix host QUUX, with the following translation 
list: 

(("BACK;" "//nd//foo//back//") 

("FRONT;" "//nd//foo//front//")) 

TTiis site apparently does not see a need to store the QFASL files in a separate directory. Note 
that the slashes are duplicated to quote them for Lisp: the actual namestrlngs contain single 
slashes as is usual with Unix. 

If the last translation’s source pattern is entirely wild, it applies to any patliname not so far 
handled. Example: 

(("BACK;" "//nd//foo//back//") 

("" "//nd//fool//*//")) 

Physical pathnames can also be back-translated into the corresponding logical pathname. This 
is the inverse transformation of ordinary translation. It is necessary to specify which logical host 
to back translate for, as it may be that the same physical pathname could be the translation of 
different logical pathnames on different hosts. Use the :back-translated-^pathname operation, 
below. 
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fs:add-1og1ca1-pathname-host logiail-liosi physical-host tramlatUms 
fs:set-logical-pathname-host logical-host &key physical-host translations 

noth create a new logical host named logical-host. Its corresponding physical host (that is, 
the host to which it should forward most operations) is physical-host, logical-host and 
physical-host should both be strings, translations should be a list of translation 
specifications, as described above. 4'he two functions differ only in tliat one accepts 
positional arguments and tlie other accepts keyword arguments. Kxamplc: 
(add-logical-pathname-host "MUSIC" "MUSIC-IO-A" 

’(("MELODY;" "SS:<MEL0DY>") 

("DOC;" "PS:<MUSIC-DOCUMENTATION>"))) 

This creates a new logical host called MUSIC. An attempt to open the file 
MUSIC:DOC;MANUAL TEXT 2 will be re-directed to the file MUS1C-10-A:PS:<MUS1C- 
DOCUMENTATION>MANUAL.TEXT.2 (assuming that die host MUS1C-10-A is a 'J’OPS-20 
system). 

fs:maka- 1 ogica 1 -pathnam 0 -host name 

Requests that tlie definition of logical host name be loaded from a standard place in the 
file system; namely, die file SYS; SITE; name TRANSLATIONS. 1'his file is loaded 
immediately witli load, in the fs package. It should contain code to create the logical 
host; normally, a call to fs:set-logical-pathname-host or fs;add-logical-pathname- 
host, above. 

The same file is automatically reloaded, if it has been changed, at appropriate times: by 
load-patches, and whenever site information is updated, 

:trans1ated-pathname Operation fs; log ical - pathname 

Converts a logical pathname to a physical padmamc. It returns die translated pathname of 
this instance, a pathname whose host component is the physical host that corresponds to 
this instance's logical host. 

If this operation is applied to a physical pathname, it simply returns that pathname 
unchanged. 

tback-translated-pathname pathname Operation oh fs;logical-pathname 

Converts a physical padmamc to a logical pathname, pathname should be a pathname 
whose host is the physical host corresponding to this instance’s logical host. This returns a 
padmamc whose host is the logical host and whose translation is pathname. If pathname 
is not the translation of any logical pathname on this instance’s host, nil is returned. 

Here is an example of how this would be used in connection with truenames. Given a 
stream that was obtained by opening a logical padmame, 

(send stream ipathname) 
returns the logical pathname diat was opened. 

(send stream :truename) 

returns die true name of the file that is open, which of course is a pathname on the 
physical host. To get this in the form of a logical pathname, one would do 
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(send (send stream :pathname) 

:back-translated-pathname 
(send stream :truename)) 

If this operation is applied to a physical patlmamc, it simply returns its argument. Thus 
die above example works no matter what kind of patlmamc was opened to create the 
stream. 

fs:unknown-logical-pathname-trans1ation (fs:pathname-error error) ComiUion 

This is signaled when a logical pathname has no translation. The condition instance 
supports die logical-pathname operation, which returns die pathname diat was 
untranslatable. 

The pnKecd type :define-directory is supported. It expects a single argument, a 
pathname or a string to be parsed into one. This defines die Uirgct pattern for a 
translation whose source pattern is die directory from the untranslatable pathname (and all 
else wild). Such a translation is added to the logical host, making it possible to translate 
the pathname. 

A logical pathname looks like "host", directory', name type version". There is no way to 
specify a device; parsing a logical pathname always returns a pathname whose device component 
is lunspecific. ITiis is because devices don't have any meaning in logical pathnames. 

The equivalence-sign character (h) can be used for quoting special characters such as spaces 
and semicolons. The double-arrow character (‘«»’) can be used as a place-holder for components 
that arc nil, and the up-horseshoc (‘U’) indicates :unspecific (generic pathnames typically have 
:unspecific as die type and the version). All letters arc mapped to upper case unless quoted. 
The :newest. :oldest, and -.wild values for versions arc written as *<’, and **’ respectively. 

There isn’t any init file naming convention for logical hosts; you can’t log into them. The 
:string-for-host, :string-for-wholine, istring-for-dired, and :string-for-editor messages are all 
passed on to the translated pathname, but the :string-for-printing is handled by the fsdogical- 
pathname flavor itself and shows the logical name. 

24.7.6 Editor Buffer Pathnames 

The hosts ED, ED-BUFFER and ED-FILE are used in pathnames which refer to buffers in 
the editor. If you open such a pathname, you get a stream that reads or writes the contents of 
an editor buffer. The three host names differ only in the syntax of the pathname, and in how it 
is interpreted. 

The host ED is followed by an abbreviation that should complete to the name of an existing 
editor buffer. For example, the pathname ED:FCX) could refer to the buffer FOO.LISP PS:<ME> 
OZ:. 

The host ED-BUFFER is followed by an exact buffer name. If there is no buffer with that 
name, one is created. This is most useful for creating a buffer. 
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The host ED-FILE is followed by an arbitrary pathname, including a host name. An ED- 
FILE pathname refers to a bulfcr visiting that file. If necessary, the file is read into die editor. 
For example, ED-FILE: OZ: PS:<ME>FOO.LISP would refer to tlie same buffer as ED: FOO. 
fhe current deftuill defaults are used in processing the patlmame tliat follows ED-FILE, when the 
pathname is parsed. 

24.8 Hosts 

F-ach host known to the Lisp Machine is represented by a flavor instance known as a host 
object. I hc host object records such things as the namc(s) of the host, its operating system type, 
and its network address(es). Flosl objects print like #cFS:TOPS20-CFlAOS-HOST "MIT-OZ"d, 
so they can be read back in. 

Not all hosts support file access. 'I'hose that do support it appear on tlic list fs:’pathname- 
host-list* and can be tlic host component of pathnames. A host object is also used as an 
argument when you make a Chaosnet connection for any purpose. 

The hosts that you can use for making network connections appear in die value of si:host- 
alist. Most of the hosts you can use for padinames arc among these; but some, such as logical 
hosts, arc not. 

24.8.1 Parsing Hostnames 

si:parse-host namestring &optional no-error-p (unknown-ok 

Returns a host object that recognizes the specified name. If the name is not recognized, 
it is an error, unless no-error-p is non-nil; in that case, nil is returned. 

If unknown-ok is non-nil (the default), a host table server on the local network is 
contacted, to see if perhaps it can find the name there. If it can’t, an error is signalled 
or nil is returned, according to no-error-p. 'I'he host instance created in this manner 
contains all the kinds of infonnation that a host defined from the host table file has. 

If a string of the form CFlAOS|/;«n is used, a host object is created and given nnn 
(interpreted as octal) as its Chaosnet address. This can be done regardless of the 
unknown-ok argument. 

Lhe first argument is allowed to be a host object instead of a string. In this case, that 
argument is simply returned. 

sys :unknown-host-name Condition 

(sys:local-network-error sys:network-error error) 

ITiis condition is signaled by si:parse-host when the host is not recognized, if that is an 
error. 

The :name operation on the condition instance returns the string given to si:parse-host. 
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si rget-host-from-address address network 

Returns a host object given an address and the name of the network which that address is 
for. Usually the symbol :chaos is used as die network name. 

nil is returned if there is no known liost with tliat address. 

fs:get-pathname-host name &optional no-error-p 

Returns a host object tliat can be used in pathnames. If the name is not recognized, it is 
an error, unless no-error-p is non-nil; in that case, nil is returned. 

I'hc first argument is allowed to be a host object instead of a string. In tliis case, that 
argument is simply returned. 

si:parse-host and fs:get-pathname-host differ in the set of hosts searched. 

fs: unknown-pathname-host (fs: path name-error error) Condition 

This condition is signaled by fs:get-pathname-host when the host is not recognized, if 
that is an error. 

'Hie :name operation on the condition instance returns the string given to fs;get- 
pathname-host. 

fs:*pathnarae-host-11st* , Variable 

ITiis is a list of all the host objects that support file access. 

s1;host-al1st Variable 

This variable is a list of one element for each known network host, 'fhe element looks 
like this: 

{full-name host-object (nickname nickname2 ... Jull-name) 
system-type machine-type site 

network list-of-addresses network! list-of addresses! . . .) 

The Jull-name is the host’s official name. The :name operation on the host object returns 
this. 

The host-object is a flavor instance that represents this host. It may be nil if none has 
been created yet; si:parse-host creates them when they are referred to. 

The nicknames are alternate names that si:parse-host should recognize for this host, but 
which are not its official name. 

The system-type is a symbol that tells what software the host runs. This is used to decide 
what flavor of host object to construct. Symbols now used include :lispm, :its, :tops-20, 
:tenex, :vms, :unix, :multics, :minits, :waits, :chaos-gateway, :dos. :rsx, :magicsix, 
■.msdos, and others. Not all of these are specifically understood in any way by the Lisp 
Machine. If none of these applies to a host you wish to add, use a new symbol. 

The machine-type is a symbol tliat describes the hardware of the host. Symbols in use 
include :lispm, :pdp10, :pdp11, :vax, :nu. :pe3230, and :ibmpc. (nil) has also been 
observed to appear here. Note that these machine types attempt to have wide meanings, 
lumping together various brands, models, etc. 
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I'hc site docs not describe anylliing about the host. Instead it serves to say what tlic l.isp 
Machine's site name was when the host was defined. Ibis is so diat, when a l.isp 
Machine system is moved to a different institution that has a disjoint set of hosts, all the 
old site's hosts can be deleted from tlic host alist by site reinitialization. 

fhe neiworka and lists of addresses describe how to reach die host. Usually there is only 
one network and only one address in the list, 'fhe generality is so that hosts with 
multiple addresses on multiple networks can be recorded. Networks include :chaos and 
:arpa. The address is meaningful only to code for a specific network. 


24.8.2 Host ObjccC Operations 

:nain8 Operation on host objecis 

Returns the ftill, official name of the host. 

:name-as-f lie-computer Operation on host objects 

Returns the name to print in padinames on diis host (assuming it supports files). ITiis is 
likely to be a short nickname of the host. 

:short-name Operation on host objects 

Returns the shortest known nickname for this host. 

:pathname-host-n amep string Operation on host objects 

Returns t if string is recognized as a name for diis host for purposes of pathname parsing. 
The local host will recognise LM as a pathname host name. 

; system-type Operation on host objects 

Returns the operating system type symbol for this host. See page 810. 

:netwoPk-type Operation on host objects 

Returns the symbol for one network that this host is connected to, or nil if it is not 
connected to any. :chaos is preferred if it is one of the possible values. 

: network-typep network Operation on host objects 

Returns t if the host is connected to the specified network. 

: network-addresses Operation on host objects 

Returns an alternating list of network names and lists of addresses, such as 
(:chaos (3104) :arpa (106357002)) 

You can therefore find out all networks a host is known to be on, and its addresses on 
any network. 

: samp 1 e- pathname Operation on host objects 

Returns a pathname for this host, whose device, directory, name, type and version 
components arc all nil. Sample pathnames arc often useful because many file-system- 
dependent pathname operations depend only on tlic pathname’s host. 


PS:<1..MAN>PATHNM.TEXT.99 


8-JUN-84 



579 


Hosts 


I isp Machtnc Miiitual 


: open-streams Opcralion on hosi objects 

Kclurns a list of all Uic open file streams for files on this host. 

tclose-all-fnes Operation on host objects 

Closes all file streams open for files on this host. 

:gener1c-base-typ» type-component Operation on host objects 

Returns the type component for a generic pathname assuming it is being made from a 
pathname whose type component is die one specified. 
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25. Accessing Files 

'Ihc l.isp Machine can access files on a variety of remote file servers, which arc typically (but 
not necessarily) accessed through tlic Chaosnet, as well as accessing files on tlic Lisp Machine 
itself, if tlic machine has its own file system. You are not allowed to refer to files without first 
logging in, and you may also need to specify a username and password for tlic host on which the 
file is stored; sec page 801. 

fhe way to read or write a file’s contents is to open the file to get an input or output stream, 

use the standard stream I/O functions or operations described in chapters 22 and 23, and then 

close tlic stream. The first .section of this chapter tells liow to open and close tlic stream. 1110 
rest of the chapter describes tilings specific to files such as deleting and renaming, finding out the 
true name of die file that has been opened, and listing a directory. 

Files arc named with pathnames. 'I’hcre is much to know about pathnames aside from 
accessing files with them; all this is described in the previous chapter. 

Many functions in this chapter take an argument called file which is intended to specify a file 

to be operated on. ITiis argurpent may be given as a pathname (which is defaulted), a namestring 

(which is parsed into a pathname and then defaulted), or a stream open to a file (the same file is 
used). 

25.1 Openinj' and Closing File Streams 

with-open-flie {stream file options...) body... Macro 

Evaluates the body forms with the variable stream bound to a stream that reads or writes 
the file named by tlie value of file. I'hc options forms evaluate to the file-opening options 
to be used; sec page 582. 

When control leaves the body, either normally or abnormally (via throw), the file is 
closed. If a new output file is being written and control leaves abnoimally, the file is 
aborted and it is as if it were never written. Because it always closes the file, even when 
an error exit is taken, with-open-file is preferred over open. Opening a large number 
of files and forgetting to close them tends to break some remote file servers, ITS’s for 
example. 

If an error occurs in opening the file, the result depends on the values of the error 
option, die if-exists option, and the if-does-not exist option. An error may be signaled 
(and possibly corrected with a new pathname), or stream may be bound to a condition 
object or even nil. 

with-open-fHe-caso {stream file options...) clauses... Macro 

This opens and closes the file like with-open-file, but what happens afterward is 
determined by clauses tliat are like the clauses of a condition-case (page 702). Each 
clause begins with a condition name or a list of condition names and is executed if open 
signals a condition that possesses any of those names. A clause beginning with the symbol 
:no-error is executed if the file is opened successfully. I’his would be where the reading 


PS:<L.MAN>FILES.'rEXT.24 


8-JUN-84 



l isp Machine Manual 


581 


Opening and Closing I 'ilc Slrcams 


or writing of die fdc would be done. 

Hxampic: 

(with-open-file-case (stream (send generic-pathname 

:source-pathname)) 

(sys:reraote-network-error (format t "~&Host down.”)) 
(fs:fne-not-found (format t "~&(New file)")) 

(:no-error (setq list (read stream)))) 

file-retry-new-pathname (pathname-var condition-names...) body... Macro 

file-retry-new-pathname-lf Macro 

cond-form (pathname-var condition-names...) body... 
file-retry-new-pathname executes body. If body does not signal any of the conditions in 
condition-names, body'f, values are simply returned. If any of condition-names is signaled, 
file-retry-new-pathname reads a new padiname, setq’s pathname-var to it. and executes 
body again. 

The user can type End instead of a pathname if he wishes to let the condition be handled 
by die debugger. 

file-retry-new-pathname-if is similar, but the conditions are handled only if cond-form'^ 
value is non-nil. 

For an example, sec the example of die following macro. 

with-open-fil e-retry Macro 

{stream {pathname-var condition-names...) options...) body... 
hike with-open-file inside of a file-retry-new-pathname. If an error occurs while 
opening the file and it has one of the specified condition-names, a new pathname is read, 
the variable pathname-var is setq’d to it, and another attempt is made to open a file with 
the newly specified name. Example: 

(with-open-file-retry (instream (infile fs:file-not-found)) 

...) 

infile should be a variable whose value is a pathname or namestring. The example is 
equivalent to 

(file-retry-new-pathname (infile fs:file-not-found) 
(with-open-file (instream infile) 

...)) 

with-open-flle-search Macro 

Opens a file, trying various patlinamcs until one of them succeeds. The pathnames tried 
differ only in their type components. For example, load uses this macro to search for 
either a compiled file or a source file. ITie calling sequence looks like 
(with-open-fi1 e-search 

{streamvar {operation defaults auto-retry) 

types-and-pathname options ...) 

body ...) 


PS:<L.MAN>FI!.ES.TEXT.24 


8-JUN-84 



Opening and Closing l-'ilc Slrcains 


582 


Lisp Machine Manual 


with-open-file-search tries opening various files until one succeeds; then binds streamvar 
to the stream and executes body, closing the stream on exit. The values of body arc 
returned. 

lypes-and-pathname specifics which files to open. It should be a form which evaluates to 
two values, die first being a list of types to try and die second being a padinamc called 
the bnsc pathname. Hiich pathname to try is made by merging die base padinamc with 
die defaults defauUs and one of die types. The types may be strings or canonical type 
keywords (see section 24.2.3, page 551). 

options arc fonns whose values should be alternating to keywords and values, which arc 
passed to open each time. 

If all the names to be tried fail, a fs:multiple-File-not-found error is signaled, operation 
is provided just so that die ;operation operation on the condition object can return it. 
Usually the value given for operation should be die user-level function for which die 
with-open-file-search is being done. 

If auto-retry is non-nil, an error causes the user to be prompted for a new base pathname. 
The endre set of types specified is Uied anew with the new pathname. 

open file &rcst options 

Returns a stream that is connected to the specified file. Unlike Maclisp, the open 
function creates streams only for files', streams of other kinds arc created by other 
functions. The file and options arguments are the same as in with-open-file; see above. 

When the caller is finished with the stream, it should dose the file by using the rclose 
operation or the close function. The with-open-file special form docs this automatically 
and so is usually preferred, open should only be used when the control structure of the 
program ncces,sitatcs opening and closing of a file in some way more complex than the 
simple way provided by with-open-file. Any program that uses open should set up 
unwind-protect handlers (see page 82) to close its files in the event of an abnormal exit. 

close stream &optional option 

Lhe close function simply sends die :close message to stream. If option is :abort for a 
file output stream, the file is discarded. 

c11:c1ose stream &kcy abort 

The Common Lisp version of close is the same as close except for its calling convention. 
If abort is non-nil for a file output stream, the file is discarded. 

fs:close-all-fnes 

Closes all open files. "Hiis is useful when a program has run wild opening files and not 
closing them. It closes all the files in :abort mode (see page 464), which means that files 
open for output are deleted. Using this function is dangerous, because you may close 
files out from under various programs like Zmacs and ZMail; only use it if you have to 
and if you feel that you know what you’re doing. 
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Vhe options used when opening a file are normally alternating keywords and values, like any 
other function tliat takes keyword arguments. In addition, for compatibility with the Maclisp 
open function, if only a single option is specified it is citlicr a keyword or a list of keywords (not 
alternating with values). 

The file-opening options control things like whether the stream is for input from a existing file 
or output to a new file, whether the file is text or binary, etc. 

'Hie following keyword tirgumcnts arc sumdardly recognized; additional keywords can be 
implemented by particular file system hosts. 

direction Controls which direction of I/O can be done on the resulting stream, fhe 
possible values are rinput (the default), routput, nil. :probe. .probe-directory 
and :probe-link. 'Ihc first two should be self-explanatory, nil or :probe means 
tltat this is a “probe” opening; no data arc to be transferred, the file is being 
opened only to verify its existence or access its properties, 'fhe stream created in 
this case does not permit any I/O. nil and :probe differ in causing different 
defaults for the argument if-does-not-exist. If tliat argument is specified explicitly, 
nil and :probe arc equivalent. 

rprobe-directory is used to sec whether a directory exists. If the directory 
specified for tlic file to be opened is found, tlicn the open completes (returning a 
non-I/O stream) as if the specified file existed whether it really exists or not. 

:probe-link is used to find out the truename of a link. If the file specified exists 
as a link, then the open completes returning a non-1/0 stream which describes 
the link itself rather than the file linked to. If the file exists and is not a link, 
the open also completes for it as with any probe. 

Common Lisp defines the value :io for this argument, requesting a stream that 
can do input and output, but no file system supported by the Lisp Machine has 
this capability. 

characters ITie possible values are t (the default), nil, which means that the file is a binary 
file, and :default, which means that the file system should decide whether the file 
contains characters or binary data and open it in the appropriate mode. 

byte-size The possible values arc nil (the default), a number, which is the number of bits 
per byte, and :default, which means that the file system should choose the byte 
size based on attributes of the file. If the file is being opened as characters, nil 
selects the appropriate system-dependent byte size for text files; it is usually not 
useful to use a different byte size. If the file is being opened as binary, nil selects 
the default byte size of 16 bits. 

element-type This is the Common Lisp way to specify what kind of objects the stream wants to 
read or write. This combines the effect of the characters and byte-size arguments. 
The value is a type specifier; it must be one of the following: 

string -char Read or write characters as usual. ITie default 

character Read or write characters, dealing with characters that are more 
than 8 bits. You can succeed in writing out any sequence of 
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character objects and reading it back, but the file docs not look 
anything like a text file. 

(unsigned-byte «) 

Read or write //-bit bytc:s. lake characters = nil, byte-size = n. 

unsigned-byte 

Similar, but uses tlic byte size tliat the file was originally written 
with, ITiis is tltc same <is characters = nil, byte-size = ;default. 

(signed-byte//) 

Read or write //-bit bytes, sign-extending on input. 1-^ch byte 
read from the file is sijjn-cxtcndcd so tliat its most significant bit 
serves as a sign bit. 

signed-byte Similar, but uses the byte size that the file was originally written 
with. 

(mod //) Like unsigned-byte for a big enough byte size to hold all 

numbers less than //. bit is also accepted, and means (mod 2). 

idefautt Is allowed, even though it is not a type specifier. It is the same 

as using :default as the value of characters. 

if-exists For output opens, if-exists specifics what to do if a file with the specified name 

already exists. There are several values )'ou can use: 

:new-version Create a new version. This makes sense only when the pathname 
has :newest as its vereion, and it is the default in that case. 

:supersede Make a new file which, when closed, replaces the old one. 

:overwrite Write over tlic data of the existing file, starting at the beginning, 

and set the file's length to the length of the newly written data, 

:truncate Like :overwrite except tliat it discards the old contents of the file 
immediately, making it empty except for what is written into it 
this time. 

:append Add new data onto the existing file at the end. 

;rename Rename the existing file and then create a new one. 
:rename-and-delete 

Rename the existing file, create a new one, and delete the old file 
when the new one is closed. 

:error Signal an error (fs:file-already-exists). This is the default when 

the pathname’s version is not :newest. I’he further handling of 
the error is controlled by the error argument. 

nil Return nil from open in this case. The error argument is 

irrelevant in this case. 

if-does-not-exist 

Specifics what to do when the file requested does not exist. There are three 
allowed values: 
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xreate Create a file. This is the default for output opens, except when 

if-exists is :append. ;overwrite or druncate. This silly exception 
is part of the Common l.isp specifications. 

terror Signal an error. This is the default for input opens, and also for 

output opens when if-exisis is tappend, toverwrite or druncate. 
The further handling of the error is controlled by the error 
argument. 

nil Return nil from open. Tliis is Uic default for tprobe opens. Ihe 

cirur argument is irrelevant in tliis case. 

Specifies what to do if an error is signaled for any reason. (Note that the values 
of the if-cxists and if-does-not-exist arguments control whether an error is signaled 
in certain circumstances.) The possible values are t (the default), treprompt and 
nil. t means that nothing special is done, so the error invokes the debugger if the 
caller docs not handle it. nil means tliat the condition object should be returned 
as the value of open, treprompt means that a new file name should be read and \ 
opened. 


Any caller which need not know reliably which file was ultimately opened might 
as well specify ireprompt for this argument. Callers which need to know if a 
different file is substituted should never specify treprompt; they may use with- 
open-file-retry or file-retry-new-pathname (see page 581) if they wish to 
permit an alternative file name to be substituted. 

isubmit If specified as t when opening a file for output, the file is submitted as a batch 

job if it is closed normally. ITie default is nil. You must specify -.direction 
;output as well. 

deleted llie default is nil. If t is specified, and the file system has the concept of deleted 

but not expunged files, it is possible to open a deleted file. Otherwise deleted 
files are invisible. 

temporary If t is specified, the file is marked as temporary, if the file system has that 
concept. The default is nil. 


preserve-dates If t is specified, the file’s reference and modification dates are not updated. The 
default is nil. 


flavor This controls the kind of file to be opened. The default is nil, a normal file. 

Other possible values are :directory and dink. Only certain file systems recognize 
this keyword. 

link-to When creating a file with flavor dink, this argument must be specified; its value is 

a pathname or namestring that becomes the target of the link, 

submit The value can be eitlier nil (the default) or t. If the value is t, and the 

:dir©ction is :output, the resulting file will be submitted as a batch job. 
Currently, this option is implemented only for Twenex and VMS. 

estimated-size The value may be nil (the default), which means there is no estimated size, or a 
number of bytes. Some file systems use this to optimize disk allocation. 
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physical-volume'\'hc value may be nil (the default), or a string that is the name of a physical 
volume on which tlic file is to be stored. I’his is not meaningful for all file 
systems. 

logical-volume 'I’he value may be nil (tlic default), oi a string tliat is the name of a logical 
volume on which the file is to be stored, lliis is not meaningful for all file 
systems. 

super-image 1’hc value may be nil (the default), or t, which disables the special treatment of 
rubout in ASCII files. Normally, rubout is an escape which causes the following 
character to be interpreted specially, allowing all characters from 0 tlirough 376 
((Ktal) to be stored. This applies to ASCII file servers only. 

raw The value may be nil (the default), or t, which disables all character set 

translation in ASCII files. This applies to ASCII file servers only. 

In tltc Maclisp compatibility mode, tliere is only one option, and it is either a symbol or a 
list of symbols. 'I’hcse symbols are recognized no matter what package they are in, since Maclisp 
docs not have packages. 'I'hc following symbols arc recognized: 

in, read Select opening for input (the default). 

out, write, print 

Select opening for output; a new file is to be created. 

binary, fixnum Select binary mode; otherwise character mode is used. Note tliat fixnum mode 
uses 16-bit binary words and is not compatible with Maclisp fixnum mode, which 
uses 36-bit words. On tlic PDP-10, fixnum files arc stored with two 16-bit words 
per PDP-10 word, left-justified and in PDP-10 byte order, 

character, ascii 

'fhe opposite of fixnum. This is the default, 
single, block Ignored for compatibility with the Maclisp open function. 

byte-size Must be followed by a number in tlie options list, and must be used in 
combination with fixnum. ITic number is the number of bits per byte, which can 
be from 1 to 16. On a PDP-10 file server these bytes will be packed into words 
in the standard way defined by the ILD8 instruction. The :tyi stream operation 
will (of course) return die bytes one at a time. 

probe, error, noerror, raw, super-image, deleted, temporary 

These arc not available in Maclisp, 'fhe corresponding keywords in the normal 
form of file-opening options are preferred over these. 
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25.2 File Stream Operations 

'The following functions and operations may be used on file streams, in addition to the 

normal I/O operations which work on all streams. Note that several of these operations are useful 

with file streams tliat have been closed. Some operations use pathnames; refer to chapter 24, 

page 545 for an explanation of pathnames. 

file-length file-stream 

Returns the length of the file open on file-stream, in terms of the units in which I/O is 
being done on tliat stream. (A stream is needed, rather tlian just a patlmame, in order to 
specify the units.) 

file-position file-stream &optional iiew-position 

With one argument, returns die current position in tlie file of file-stream, using tlie 
rread-pointer stream operation. It may return nil meaning tliat tlie position cannot be 
determined. In fiict, it always returns nil for a stream open in character mode and not at 
the beginning of the file. 

With two arguments, sets the position using the :set-pointer stream operation, if possible, 
and returns t if the setting was possible and nil if not. You can specify :start as the new 
position to position to the beginning of the file, or :end to position to the end. 

: pathname Operation on file streams 

Returns the pathname that was opened to get this stream. This may not be identical to 
the argument to open, since missing components will have been filled in from defaults. 
The pathname may have been replaced wholesale if an error occurred in the attempt to 
open the original pathname. 

:truename Operation on file streams 

Returns the pathname of the file actually open on this stream. This can be different from 
what :pathname returns because of file links, logical devices, mapping of version :newest 
to a particular version number, etc. For an output stream the truename is not meaningful 
until after the stream has been closed, at least when the file server is an ITS. 

: generic-pathname Operation on file streams 

Returns the generic pathname of the pathname that was opened to get this stream. 
Normally this is the same as the result of sending tlie :generic-pathname message to the 
value of the :pathname operation on the stream; however, it docs special things when 
the Lisp system is bootstrapping itself. 

:qfas1p Operation on file streams 

Returns t if the file has a magic flag at the front that says it is a QFASL file, nil if it is 
an ordinary file. 

: length Operation on file streams 

Returns the length of the file, in bytes or characters. For text files on ASCII file servers, 
this is the number of ASCII characters, not Lisp Machine characters. The numbers are 
different because of character-set translation; see section 25.8, page 607 for a full 
• explanation. For an output stream the length is not meaningful until after the stream has 
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been closed, ai least when the file server is an FI'S. 

:creat1on-date Openuion on file streams 

Returns the creation date of the file, as a number that is a universal time. Sec the 
chapter on the time package (chapter 34, page 776). 

:1nfo Operation on file streams 

Returns a cons of tlic file’s irucnamc and its creation date. This can be used to tell if the 
file has been modified between two open’s. L'or an output stream the infonnation is not 
guaranteed to be correct until after die stream has been closed. 

:prop0rt1es Aoptional (error-p t) Operation on file streams 

This returns two values: a property list (like an element of the list returned by 
fs:directory-list), and a list of tlie settable properties. See tlie section on standard file 
properties (section 25.6, page 598) for a description of tlie ones that may possible found 
in die list. 

:S 8 t-byte-sl 20 new-byte-size Operation on file streams 

This is only allowed on binary file streams. The byte size can be changed to any number 
of bits from 1 to 16. 

: delete &optional (errorp t) Operation on file streams 

Deletes die file open on this stream. For tlie meaning of errorp, sec the delete! 
function. I’he file doesn’t really go away until die stream is closed. 

: undelete &optional (errorp t) Operation on file streams 

If you have used die :deleted option in open to open a deleted file, this operation 
undeletes die file. 

; rename new-name &optional (errorp t) Operation on file streams 

Renames the file open on this stream. For tlie meaning of errorp, see the rename! 
function. 

File output streams implement the :!inish and :!orce-output operations. 

25.3 Manipulating Files 

This section describes functions for doing things to files aside from reading or writing their 

contents. 

true name object 

Returns the truename of the file specified somehow by object. If object is a plausible 
stream, it is asked for the truename with die :truename operation. Otherwise, object is 
converted to a pathname and that pathname is opened to get its file’s truename. 
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delete-file file &kcy (error-/) t) query? 
deletef file &optional (envi-pX) query? 

Both delete tlic specified file. I’hc two functions differ in accepting keyword arguments 
versus positional arguments, file may contain wildcard characters, in which ease multiple 
files arc deleted. 

If query^? is non-nil, the user is queried about each file (whether there arc wildcards or 
not). Only tlic files that die user confirms arc actually deleted. 

If error-p is t. then if an error occurs it is signaled as a Lisp error. If errot'-p is nil and 
an error occurs, die error mcssiige is returned as a condition object. Otherwise, the value 
is a list of elements, one for each file considered. 'I'he car of each clement is the 
truename of the file, and the cadr is non-nil if the file was actually deleted (it is always t 
unless querying was done). 

undalete-flie file {error-p\) query? 

undeletef file &optional {errot^pX) query? 

Both undelete the specified file. Wildcards arc allowed, just as in deletef. ITic rest of 
die calling conventions arc the same as well. I'he two functions differ in taking keyword 
arguments versus positional arguments. 

Not all file systems support undeletion, and if it is not supported on the one you are 
using, it gets an error or returns a string according to error-p. To find out whether a 
particular file system supports this, send the ;undeletable-p operation to a pathname. If 
it returns t, the file system of that pathname supports undeletion. 

rename-file file new-name &key (erro^/»t) qyiery? 
renamef file new-name &optional {error-pi) query? 

Both rename the specified file to newname (a pathname or string). The two functions 
differ in taking keyword arguments versus positional arguments, file may contain 
wildcards, in which case multiple files are renamed. Each file’s new name is produced by 
passing newname to merge-pathname-defaults with the file’s truename as the defaults. 
Therefore, newname should be a string in this case. 

If query? is non-nil, the user is queried about each file (whether there are wildcards or 
not). Only the files that the user confirms are actually renamed. 

If error-p is t, then if an error occurs it is signaled as a. Lisp error. If error-p is nil and 
an error occurs, the error message is returned as a condition object. Otherwise, the value 
is a list of elements, one for each file considered, llie car of each clement is the original 
truename of the file, the cadr is the name it was to be renamed to, and the caddr is 
non-nil if the file was renamed. The caddr is nil if the user was queried and said no. 

Copy-f11« file newname &key (errort) {copy-creation-datei) {copy-author^ report-stream 
{create-directories {characters ■.6e\9.\i\i) (6>’re-s/ze :default) 

Copies the file specified by file to the name newname. 
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characters and byte-size specify what mode of L'O to use to transfer the data, characters 
can be 


t 

nil 

;ask 

:maybe-ask 

:default 


to specify character input and output, 
for binary input and output, 
meaning ask the user which one 

meaning ask if it is not possible to tell with certainty which method is 
best, 

meaning to guess as well as possible automatically. 


If binary transfer is done, byte-size specifics die byte size to use; :default means to ask 
die file system for the byte size that die old file is stored in, just as it docs in open. 

copy-author and copy-creation-date say whether to set those properties of the new file to be 
die same as diosc of die old file. If a property is not copied, it is set to your login name 
or die current date and time. 

report-stream, if non-nil, is a stream on which a message should be printed describing the 
file copied, where it is copied to, and which mode was used. 

create-directories says what to do if the output filename specifics a directory that does not 
exist. It can be t meaning create the directory, nil meaning treat it as an error, or :query 
meaning ask die user which one to do, I'hc default is :query. 


error, if nil, means that if an error happens then this function should Just return an error 
indication. 

If the pathname to copy from contains wildcards, multiple files are copied. The new 
name for each file is obtained by merging new-name (parsed into a pathname) with that 
file’s truenamc as a default. 'ITie mode of copy is determined for each file individually, 
and each copy is reported on the report-stream if there is one. If error is nil, an error in 
copying one file docs not prevent the others from being copied. 


There arc four values. If wildcards were used, each value is a list with one element 
describing each file that matched; otherwise, each value describes the single file specified 
(though the value may be a list anyway). The values, for each file, are: 

output-file Ihc defaulted pathname to be opened for output in copying this file. 

truename 'I’hc truenamc of the file copied 


outcome The truename of the new file. If the file was successfully copied. A 
condition object, if there was an error and error was nil, nil if the user 
was asked whether to copy this file and said no. 

mode A Common Lisp type descriptor such as string-char or (unsigned-byte 

8) saying how the file was copied. 
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probe-fHe file 
probef file 

Returns nil if there is no file named file\ otherwise returns a pathname tliat is the true 
name of the file, which can be different from j?/e because of file links, version numbers, 
etc. If file is a stream, tliis function cannot return nil. 

Any problem in opening the file except for fs;file-not-found signals an error. 

probef is the MjKlisp name: probe-file is the Common l.isp name. 


fHe-write-dato file 

Returns the creatkm date/time of file, as a universal time. 

file-author file 

Returns the name of the author of file (the user who wrote it), as a su ing. 

viewf file &optional (ow/pM/-s/renw *standard-output*) leader 

Copies the contents of the specified file, opened in character mode, onto output-stream. 
Normally this has the effect of printing the file on the terminal, leader is passed along to 
stream-copy-until-eof (sec page 457). 

fs:create-11nlc link-mme link-to &key (errort) 

Creates a link named link-name which points to a file named link-to. An error happens if 
the host specified in link-name does not support links, or for any of the usual problems 
that can happen in creating a file. 

25.3.1 Loading Files 

To load a file is to read through the file, evaluating each form in it. Programs are typically 
stored in files: the expressions in the file are mostly special forms such as defun and defvar 
which define the functions and variables of the program. 

Loading a compiled (or QFASL) file is similar, except that the file does not contain text but 
rather pre-digested expressions created by the compiler which can be loaded more quickly. 

These functions are for loading single files. There is a system for keeping track of programs 
which consist of more than one file; for further information refer to chapter 28, page 660. 


load file &key verbose print (if-does-not-exist\) set-default-pathmme package 

Loads the specified file into the Lisp environment. If file is a stream, load reads from it; 
otherwise file is defaulted from the default pathname defaults and the result specifies a file 
to be opened. If the file is a QFASI. file, fasload is used: otherwise readfile is used. If 
file specifics a name but no type, load looks first for the canonical type :qfasl and then 
for the canonical type :lisp. 

Normally the file is read into the package specified in its attribute list, but if package is 
supplied then the file is read in that package. If package is nil and verbose is nil, load 
prints a message saying what file is being loaded and what package is being used, verbose 
defaults to the value of ‘load-verbose*. 
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If if-does-Hoi-exis! is nil, load just returns nil if no file with the specified name exists. 
Krror conditions other Uian fs:file-not-found arc not handled by this option. 

If a file is loaded, load returns the file’s truenanic. 

If print is non-nil, tlic value of each expression evaluated from the file is printed on 
*standard-output*. 

pathname is defaulted from the default pathname defaults. If set-default-pathname is non- 
nil, die patlmame defaults are set to tlie name of die file loaded. The default for set- 
default-pathname is t. 

load used to be called with a different calling sequence: 

(load pathname pkg nonexistent-ok 
dont-set-default) 

'Phis calling sequence is detected and still works, but it is obsolete. 

•load-verbose* Variable 

Is die default value for the verbose argument to load. 

readftle file &optional pkg no-msg-p 

readfife is the version of load for text files. It reads and evaluates each expression in the 
file. As with load, pkg can specify what package to read the file into. Unless no-msg-p is 
t, a message is printed indicating what file is being read into what package. 

fas load file Aopdonal pkg no-msg-p 

fasload is the version of load for QFASL files, It defines functions and performs other 
actions as directed by the specificadons inserted in the file by the compiler. As with load, 
pkg can specify what package to read the file into. Unless no-msg-p is t, a message is 
printed indicating what file is being read into what package. 


25.4 Pathname Operations That Access Files 

Here are the operations that access files. Many accept an argument error or error^p which 
specifies whether to signal an error or to return a condition instance, if the file cannot be 
accessed. For these arguments, nil and non-nil are the only significant values. ;reprompt has no 
special meaning as a value. That value when passed to one of the file accessing functions (open, 
deletef, etc.) has its special significance at a higher level. 

:truename Operat/on oh pathname 

Returns a pathname object describing the exact name of the file specified by the pathname 
the object is sent to. 

This may be different from the original pathname. For example, the original pathname 
may have rnewest as the version, but the truename always has a number as the version if 
the file system supports versions. 
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ropen pathname &rc$i options Operation on pathname 

Opens a stream for tJte file named by the pathname. The argument pathname is what the 
;pathname operation on the resulting stream should return. When a logical pathname is 
opened, pathname is that logical pathname, but self is its translated pathname. 

options is a list trf" alternating keywords and values, as would be passed to open. 'I'he old 
style of open keywords are not allowed; when they are used with open, open converts 
them to the new style before sending the :open message. 

t 

: delete &optional (error-p ^ * Operation on pathname 

: undelete &optiohal {errorp t) Operation on pathname 

Respectively delete or undelete the file specified by tlie patliname. 

All file systems support :delete but not all support undelete. 

If error-/? is nil, problems such as nonexistent files cause a string describing the problem 
to be returned. Otherwise, they signal an error. 

:und8ldtab1e-p Operation onpathname 

Returns t if this pathname is for a file system which allows deletion to be undone. Such 
pathnames support tlic undelete and texpunge operations. 

: rename new-name &optional {errorp t) Operation on pathname 

Renames the file specified by the pathname. newname, a string or pathname, specifies 
the name to rename to. If it is a string, it is parsed using self as the defaults. 

if errorp is nil, problems such as nonexistent files cause a string describing the problem 
to be returned. Otherwise, they signal an error. 

: complete-string string options Operation on pathname 

Attempts to complete the filename string, returning the results. This operation is used by 
the function fs:complete-pathname (see page 602). The pathname the message is sent to 
is used for defaults, options is a list whose elements may include :deleted, :read (file is 
for input), :write (it’s for output), :old (only existing files allowed), or :new-ok (new files 
are allowed too). 

There are two values: a string, which is the completion as far as possible, and a flag, 
which can be :old, :new or nil. :old says that the returned string names an existing file, 
:nevw says that the returned string is no file but some completion was done, nil says that 
no completion was possible. 

: change-properties errorp &rcst properties Operation on pa^name 

Changes the properties of the file specified by the pathname, properties should be an 
alternating list of property names and values. 
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: d 1 rectory-11st options 


Operation on pathname 


Pcrfonns the work t)f (fs:directory-list this-pathname options...). 


’.properties Operation on pathname 

Returns a property list (in tlte fonn of a directory-list element) and a list of settable 
properties. See section 25.6, page 598 for more information on file properties. 

: wildcard-map function plistp dii^list-options &rest args Operation on pathname 

Maps function over all tlie files specified by Uiis patliname (which may contain wildcards). 
Kach time is called, its first argument is a pathname with no wildcards, or else a 

directory-list clement (whose car is a pathname and whose edr contains property names 
and values). 'I hc elements of args arc given to function as additional arguments. 

plistp says whether function's first argument should be a directory-list clement or just a 
patliname. t specifies a directory-list clement. That provides more information, but it 
makes it necessary to do extra work if the specified pathname does not contain wildcards. 

dir-list-options is passed to fs:directory-list. You can use this to get deleted files 
mentioned in the list, for example. 

The remaining file-access operations are defined only on certain file systems. 

: expunge &key (error t) Operation on pathname 

Expunges tlic directory specified by the host, device and directory components of the 
pathname. 

The argument error says whether to signal an error if the directory docs not exist, nil 
means just return a string instead. 

:create-d1 rectory &key (error t) Operation on pathname 

Creates the directory specified in this pathname. 

: remote-connect &kcy (error t) access Operation on pathname 

Performs the work of fs:remote-connect with the same arguments on this pathname’s 
host. 

25.5 File Attribute Lists 

Any text file can contain an attribute list that specifies several attributes of the file. The above 
loading functions, tlic compiler, and the editor look at this property list. Attribute lists are 
especially useful in program source files, i.e. a file that is intended to be loaded (or compiled and 
then loaded). QFASL files also contain attribute lists, copied from their source files. 

If the first non-blank line in a text file contains the three characters some text, and 
♦ again, the text is recognized as the file’s attribute list. Each attribute consists of the attribute 
name, a colon, and the attribute value. If there is more than one attribute they are separated by 
semicolons. An example of such an attribute list is: 

; ModeiLisp; Package:Cenophane; BaserlO 
This defines three attributes: mode, package, and base. ITie initial semicolon makes the line 
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look like a comment ratlier than a Lisp expression. Another example is: 

.c Part of the Lisp Machine manual. ModeiBolio 

An attribute name is made up of letters, numbers, and othcrwisc-tindefincd punctuation 
characters such as hyphens. An attribute value can be such a name, or a decimal number, or 
several such items separated by commas. Spaces may be used freely to separate tokens. Upper 
and lower-case letters are not distinguished. 'ITiere is no quoting convention for special characters 
such as colons and semicolons. 

If die attribute list text contains no colons, it is an old Kmacs format, containing only the 
value of tlie Mode attribute. 

Lhc file attribute list format actually has nothing to do with Lisp; it is just a convention for 
placing some information into a file that is easy for a program to interpret. The l^macs editor on 
tlie PDP-IO knows how to interpret these attribute lists (primarily in order to look at tlie Mode 
attribute). 

Lhe Lisp Machine handles the attribute list stored in the file by parsing it into a Lisp data 
structure, a property list. Attribute names are interpreted as Lisp symbols and are interned on the 
keyword package. Numbers are interpreted as Lisp fixnums and are read in decimal. If a 
attribute value conuins any commas, then the commas separate several expressions that are 
formed into a list 

When a file is compiled, its attribute list data structure is stored in the QFASL file. It can 
be loaded back from the QFASL file as well. The representation in the QFASL file resembles 
nothing described here, but when the attribute list is extracted from there, the same Lisp data 
structure described above is obtained. 

When a file is edited, loaded, or compiled, its file attribute list is read in and the properties 
are stored on the property list of tlie generic pathname (see section 24.5, page 561) for that file, 
where they can be retrieved with the :get and :plist messages. This is done using the function 
fs:read-attribute-list, below. So the way you examine the properties of a file is usually to use 
messages to a pathname object that represents the generic pathname of a file. Note that there are 
other properties there, too. 

Here the attribute names with standard meanings: 

Mode The editor major mode to be used when editing this file. This is typically the 

name of the language in which the file is written. The most common values are 
Lisp and Text. 

Package This attribute specifics the package in which symbols in the file should be 
interned. The attribute may be either the name of a package, or a list that 
specifies both the package name and how to create the package if it does not 
exist. If it is a list, it should look like (name superpackage initial-size ...options...). 
See chapter 27, page 636 for more information about packages. 

Base The number base in which the file is written (remember, it is always parsed in 

decimal). ITiis affects both ’read-base* and *print-base*, since it is confusing 
to have the input and output bases be different. 'ITie most common values are 8 
and 10. 
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Readtable 'I'he value specifies the syntax (that is, the choice of readUible) to use for reading 
Lisp objects from this file. I'he defined values are t or traditional for traditional 
l.isp Machine syntitx, and Cl or common-lisp for Common Lisp syntax. If you 
do not specify this option, the objects in the file arc read using whatever 
readtable is current in tlic program tliat reads them. 

Lowercase If tlic attribute value is not nil, tlic file is written in lower-case letters and the 
editor d(ics not translate to upper case. (The editor docs not translate to upper 
case by default unless the user enables Idcctric Shift L(x:k mode.) 

Fonts The attribute value is a list of font names, separated by commas. 'I’he editor uses 

this for files that arc to be displayed in a specific font, or contain multiple fonts. 
If this attribute is presenL tlie file is actually stored in die file system with font- 
change indicators. A font-change indicator is an epsilon (r) followed by a digit or 
*. rn means to enter font n. The previous font is saved on a stack and e* 
means to pop the stack, returning to the previous font. If tlie file includes an 
epsilon as part of its contents, it is stored as ee. 

When expressions are read from such files, font-change indicators are ignored, and 
££ is treated as a single £. 

Backspace If the attribute value is not nil. Overstrike characters in the file should cause 
characters to overprint on each other, 'fhe default is to disallow overprinting and 
display Overstrike the way other special function keys are displayed. 'Phis default 
is to prevent the confusion that can be engendered by ovcrstruck text. 

Patch-File If the attribute value is not nil, the file is a paich file. When it is loaded the 
system will not complain about function, redefinitions. In a patch file, the defvar 
special-form turns into defconst; thus patch files always reinitialize variables. 
Patch files are usually created by special editor commands described in section 
28.8, page 672. 

Cold-Load A non-nil value for this attribute identifies files that are part of die cold load, the 
core from which a new system version is built. Certain features that do not work 
in the cold load check this flag to give an error or a compiler warning if used in 
such files, so diat the problem can be d<;tccted sooner. 

You are free to define additional file attributes of your own. However, to avoid accidental 
name conflicts, you should choose names that arc different from all the names above, and from 
any names likely to be defined by anybody clse’s programs. 

The following functions are used to examine file attribute lists: 
fs:fne-attr1bute-l1st pathname 

Returns the attribute list of the file specified by the pathname. This works on both text 
files and QFASL files. 
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fsiextract-attrllwte-Tlst stream 

Returns the sattribulc list read from the specified stream, which should be pointing to the 
beginning of a file. 'ITiis works on both text streams and QFASL file binary streams. 
After the attribute list is read, the stream’s pointer is set back to tlie beginning of the file 
using the :set-pointer file stream operation (see page 468). 

fs:P0ad-attribute-T1st stream 

pathname should be a pathname object (not a string or namelist, but an actual pathname); 
usually it is a generic pathname (see section 24.5, page 561). stream should be a stream 
that has been t^ned and is pointing to the beginning of the file whose file attribute list 
is to be parsed. The attribute list is read from tlie stream and then coiresponding 
properties arc placed on the specified pathname. Fhe attribute list is also returned. 

The fundamental way that programs in the Lisp Machine notice the presence of properties on 
a file’s attribute list is by examining the property list in the generic pathname. However, there is 
another way that is more convenient for some applications. File attributes can cause special 
variables to be bound whenever Lisp expressions are being read from the file—when the file is 
being loaded, when it is being compiled, when it is being read from by the editor, and when its 

QFASL file is being loaded. This is how the Package and Base attributes work. You can also 

deal with attributes this way, by using the following function: 

fs:f 1 te-attPlbute-blndlngs pathname 

Returns values describing the special variables that should be bound before reading 
expressions from file pathname. It examines the property list of pathname and finds all 
those property names that have fs:file-attribute-bindings propenics. Each such property 
name specifies a set of variables to bind and a set of values to which to bind them. This 
function returns two values, a list of all the variables and a list of all the corresponding 
values. Usually you use this function by calling it on a generic pathname that has had 

fsrread-attribute-list done on it, and then you use the two returned values as the first 

two arguments of a progv special form (see page 32). Inside the body of the progv the 
specified bindings will be in effect 

pathname may be anything acceptable as the first argument of get. Usually it is a generic 
pathname. 

Of the standard attribute names, the following ones have fs:file-attribute-bindings, with 
the following effects. Package binds the variable package (see page 637) to the package. 
Base binds the variables *print-base* (see page 514) and ’read-base* (see page 517) to 
the value. Readtable binds the variable readtable to a value computed from the 
specified attribute. Patch-file binds fs:this-is-a-patch-file to the value. Cold-load 
binds si:file-in-cold-load to the value. Fonts binds sirread-discard-font-changes to t. 

Any properties whose names do not have fs:file-attribute-bindings properties are ignored 
completely. 

You can also add your own attribute names that affect bindings. If an indicator symbol 
has an fs:flle-attribute-bindings property, the value of that property is a function that is 
called when a file with a file attribute of that name is going to be read from. The 
function is given three arguments: the file pathname, the attribute name, and the 
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attribute value. It must return two values: a list of variables to be bound and a list of 
values to bind them to. The function for the Elase keyword could have been defined by: 
(defun (:base file-attribute-bindings) (file ignore bse) 

(if (not (and (typep bse ’fixnum) 

(> bse 1) 

(< bse 37.))) 

(ferror ’fs:invalid-file-attrbute 

"File.~A has an illegal Base;~D 
file bse)) 

(values (list ’base ’ibase) (list bse bse))) 

fs:extract-attribute-b1ndings stream 

Returns two values: a list of variables, and a corresponding list of values to bind them 
to, giving the attribute bindings of the attribute list found on stream 

fs:1nval1d-flie-attribute (error) Condition 

An attribute in the file attribute list had a bad value. This is detected within fs:file- 
attribute-bindings. 

25.6 Accessing Directories 

To understand the functions in this section, it.is vital to have read the chapter on pathnames. 
The filespec argument in many of these functions may be a pathname or a namestring; its name, 
type and version default to :wild. 

I1stf filespec 

Prints on ‘standard-output* the names of the files that match filespec, and their sizes, 
creation dates, and other information that comes in the directory listing, 

fs:directory-11st filespec &rcst options 

Finds all the files tliat match filespec and returns a list with one element for each file. 
Each clement is a list whose car is the pathname of the file and whose edr is a list of the 
properties of the file; thus the element is a disembodied property list and get may be 
used to access the file’s properties. The car of one element is nil; the properties in this 
element arc properties of the file system as a wfiole rather than of a specific file. 

filespec normally contains wildcards, and the data returned describe all existing files that 
match it. If it contains no wildcards, it spcjcifies a single file and only that file is 
described in the data that are returned. 

Tire options are keywords which modify the operation. The following options are currently 
defined: 

:noerror If a file-system error (such as no such directory) occurs during the 
operation, normally an error is signaled and the user is asked to supply a 
new pathname. However, if :ncierror is specified then, in the event of an 
error, a condition object describing the error is returned as the result of 
fs:directory-list. 'fhis is identical to the :noerror option to open. 
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:deleted ’lliis is for file servers on which deletion is not pennanent. It specifics 
that deleted (but not yet expunged) files are to be included in the 
dtra’tory listing. 

:sorted 'ITifS requests that die directory list be sorted by filenames before it is 

returned. 

The properties that may appear in the list of property lists returned by fs:directory-list 
arc host-dependent to some extent. The following properties arc tliosc tliat arc defined for 
both ITS and 'rOPS-20 file servers. This set of properties is likely to be extended or 
changed in the future. 

:length-in-bytes 

The length of tlic file expressed in terms of tlte basic units in which it is 
written (characters in the case of a text file). 

:byte-size rhe number of bits in one of Uiosc units. 

:length-in-blocks 

Ihe lengUi of the file in terms of the file system’s unit of storage 
allocation. 

:block-size I'he number of bits in one of those units. 

:creation-date ’Fhe date die file was created, as a universal time. See chapter 34, page 
776. 

:reference-date 

The most recent date on which the file was used, as a universal dme or 
nil, meaning the file was never referenced. 

:modification-date 

The most recent date on which the file’s contents were changed, as a 
universal dme. 

.'author The name of the person who created the file, as a string. 

:reader The name of the person who last read the file, as a string. 


:not-backed-up 



t if the file exists only on disk, nil if it has been backed up on magnetic 
tape. 

:directory 

t if this file is actually a directory. 

.'temporary 

t if this file is temporary. 

:deleted 

t if this file is deleted. Deleted files are included in the directory list only 
if you specify the :deleted option. 

:dont-delete 

t indicates that the file is not allowed to be deleted. 

:dont-supersede 

t indicates that the file may not be superseded; that is, a file with the 
same name and higher version may not be created. 

:dont-reap 

t indicates that this file is not supposed to be deleted automatically for 
lack of use. 
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:dont-dump t indicates dial tliis file is not supposed to be dumped onto magnetic tape 
for backup purposes. 

:characters t indicates that tliis file contains characters (that is. text), nil indicates that 
the file contains binary daUi. This property, rather than die file’s byte 
size, should be used to decide wlicdicr it is a text file. 

:link-to If the file is a link, diis property is a string containing the name that the 

link points to. 

:offline T if the file’s contents arc not online. 

:incremental-dump-date 

fhe last time diis file was dumped during an incremental dump (a 
universal time). 

:incremental-dump-tape 

The tape on which the last was saved in that incremental dump (a string). 
:complete-dump-date 

'I’hc last dme diis file was dumped during an full dump (a universal time). 
:complete-dump-tape 

'fhe tape on which the last was saved in that full dump (a string). 
:generation-retention-count 

I'he number of files differing in version that are kept around. 
;default-generation-retention-count 

I'he gencration-rctcntion-count dial a file ordinarily gets when it is created 
in this directory. 

;auto-expunge-interval 

The interval at which files are expunged from this directory, in seconds, 

:d ate - last - expunged 

'I'he last (universal) time this directory was expunged, or nil. 

:account 'fhe account to which the file belongs, a string. 

:protection A system-dependent description of the protection of this file as a string. 
:physical-volume 

A string naming the physical volume on which the file is found. 

:volume-name 

A string naming the logical volume on which the file is found. 

:pack-number A string describing the pack on which this file is found. 

:d isk - space-description 

A system-dependent description of the space usage on the file system. 
This usually appears in the plist that applies to the entire directory list 

'fhe element in the directory list that has nil instead of a file’s pathname describes the 
directory as a whole. 
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:physical-volume - free - blocks 

'riiis property is an itlist in which each element maps a physical volume 
name (a string) into a number, tliat is the number of free blocks on tJiat 
volume. 

:settable-properties 

t his property is a list of file property names that may be set. This 
information is provided in tlie directory list because it is different for 
different file systems. 

pathname fhis property is the pathname from which Utis directory list was made. 

:block-size This is the numl^er of words in a bkKk in this directory. It can be used 

to interpret tlie numbers of free blocks. 

fs:d1rectory-Hst-stream filespec &TC$t options 

This is like fs:directory-list but returns the information in a different fonn. Instead of 
returning the directory list all at once, it returns a special kind of stream which gives out 
one element of the directory list at a time. 

The directory list stream supports two operations: :entry and :close. :entry asks for the 
next element of the directory stream. :cIosg closes any connection to a remote file server. 

The purpose of using fs:directory-list-stream instead of fs:directory-llst is that, when 
communicating with a remote file server, the directory list stream can give you some of 
the information without waiting for it to all be transmitted and parsed. This is desirable 
if the directory is being printed on the console. 

directory filespec 

Returns a list of pathnames (truenames) of the files in the directory specified by filespec. 
Wildcards arc allowed. This is the Common Lisp way to find the contents of a directory. 

fstexpungo-directory y?/esp<?c &key (cm?rt) 

Expunges the directory specified in filespec, that is, permanently eliminates any deleted 
files in that directory. If error is nil, there is no error if the directory docs not exist. 

Note that not all file systems support this function. To find out whether a particular one 
does, send the :undeletable-p operation to a pathname. If it returns t, the file system of 
that pathname supports undeletion (and therefore expunging). 

fs:creato-d1 rectory filespec &key (errort) 

Creates the directory specified in filespec. If error is nil, there is no error if the directory 
cannot be created; instead an error string is returned. Not all file servers support creation 
of directories. 

fs:remote-connect &key (errort) access 

Performs the TOPS-20 “connect” or “access” function, or their equivalents, in a remote 
file server. Access is done if access is non-nil; otherwise, connect is done. 
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The connect operiiiion grants you full access to the specified directory. The access 
operation grants you whatever access to all files and directories you would have if logged 
in on the specified directory. Both operations affect access only, since the connected 
directory of die rcmt)tc server is never used by die Tisp Machine in choosing which file 
to .operate on. 

This function may ask you for a password if one is required for die directory you specify. 
If the operation cannot be performed, dien if error is nil, an erroMibject is returned. 

f ile Properties: 

fs: change-file-properties file error-p &rest properiies 

Changes one or more properties of the file file, 'llie properiies arguments are alternating 
keywords and values. If an error (K'curs accessing the file or changing die properties, the 
errorp argument controls what is done; if it is nil, a condition object describing the error 
is returned: if it is t a l.isp error is signaled. If no error tKcurs, fs:change-file- 
properties returns t. 

Only some of the properties of a file may be changed; for instance, its creation date or 
its author. Exactly which properties may be changed depends on the host file system; a 
list of die changeable property names is die :i5ettable-properties property of the file 
system as a whole, returned by fs:directory-list as explained above. 

fs:file-properties file &optional (error-pX) 

Returns a disembodied property list for a single; file (compare this to fs:directory-list). 
The car of die returned list is die truename of the file and die edr is an alternating list of 
indicators and values. The errorp argument is the same as in fs:change-file-properties. 

Filename Completion: 

fs:complete-pathname defaults siring type version &rest options 

siring is a partially-specified file name. (Presumably it was typed in by a user and 
terminated with the Altmode key or the End key to request completion.) fs:complete- 
pathname looks in the file system on die appropriate host and returns a new, possibly 
more specific string. Any unambiguous abbreviations are expanded out in a host- 
dependent fashion. 

defaults, type, and version are the arguments to be given to fs:merge-pathname- 
defaults (see page 558) when the user’s input is eventually parsed and defaulted. 

options are keywords (without following values) that control how the completion is 
performed. The following option keywords are allowed: 

:deleted Looks for files which have been deleted but not yet expunged, 

:read or :in The file is going to be read. This is the default. 

:print or :write or ;out 

ITic file is going to be written (i.e. a new version is going to be created). 
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l.ooks only for files Uiai already exist. ’Ihis is die default. 

Allows either a file that already exists or a file that does not yet exist An 
example of the use of this is the C-X C-F (Find File) command in the 
editor. 

The first value returned is always a string containing a file name, either die original string 
or a new, more specific string. I he second value returned indictites the success or failure 
of the completion. It is nil if an error occurred. One possible error is dial die file is on 
a file system that does not support completion, in which case the original string is 
returned unchanged. Other possible second values arc lold, which means that die stiing 
completed to the name of a file that exists, mew, which means that the string completed 
to the name of a file that could be created, and nil again, which means dial there is no 
possible completion. 

Balance Directories: 

fs:ba1anc8-d1rector1es filespecl filespecl «&rcst options 

fs:balance-directories is a ametion for maintaining multiple copies of a directory. Often 
it is useful to maintain copies of your files on more than one machine, this function 
provides a simple way of keeping those copies up to date. 

The function first parses filespecl, filling in missing components with wildcards (except for 
the version, which is :newest). I’hen filespec2 is parsed with filespecl as the default. ITie 
resulting pathnames are used to generate directory lists using fs:directory-list. Note that 
the resulting directory lists need not be entire directories: any subset of a directory that 
fs:directory-list can produce will do. 

First the directory lists are matched up on the basis of file name and type. All of the 
files in either directory list which have both the same name and the same type are 
grouped together. 

The directory lists are next analyzed to determine if the directories are consistent, meaning 
that two files witli the same name and type have equal creation-dates when their versions 
match, and greater versions have later creation-dates. If any inconsistencies are found, a 
warning message is printed on the console. 

If the version specified for both filespecl and//cspec2 was :newest (the default), dien the 
newest version of each file in each directory is copied to the other directory if it is not 
already there. The result is that each directory has the newest copy of every file in either 
of the two directories. 

If one or both of the specified versions is not :newest, then every version that appears in 
one directory list and not in the other is copied, fhis has the result that the two 
directories arc completely the same, (Note that this is probably not the right thing to use 
^ to copy an entire directory. Use copy-file with a wildcard argument instead.) 

The options are keywords arguments which modify the operation. The following options 
are currently defined: 


:old 

:new-ok 
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:ignore 

:error 


This option takes one argumcnl, which is a list of file names to ignore 
when making the directory lists. The default value is nil. 

'Iliis option is identical to tlic :error option to open. 


:query-mode Thisoption takes one argument which indicates whether or not the user 
should be asked before files are transferred. If tltc argument is nil. no 
querying is done. If it is :1->2, then only files being transferred from 
filespec2 to fiksped arc queried, while if it is :2->1, then files transferred 
from fikaped to fikspcc2 arc qi\mcd. If the argument is :always, tltcn 
tltc user is asked about all files. 

:copy-mocle 'Ibis option is identical to tlic :copy-mode option of copy-file, and is 
used to control whether files arc treated as binary or textual data. 


:direction This option specifics transfer of files in one direction only. If the value is 
:1 ->2 tlicn files arc transfered only from fiksped to fikspec2, never in the 
other direction. If tlic value is :2->1 then files arc transferred only from 
fikspec2 lo fiksped. nil, the default, means transfer in cither direction as 
appropriate. 


25.7 Errors in Accessing Files 

fs:f ile-erroP (error) Condition Flavor 

'Ibis flavor is the basis for all errors signaled by the file system. 

It defines two special operations. :pathname and :operation. Usually, these return the 
pathname of the file being operated on, and the operation used. This operation was 
performed cither on the pathname object itself, or on a stream. 

It defines prompting for the proceed types :r€!try-file-operation and :new-pathname, 
both of which arc provided for many file errors. :retry-file-operation tries the operation 
again exactly as it was requested by the program; mew-pathname expects on argument, 
a pathname, and tries the same operation on this pathname instead of the original one. 

fstflle-operatlon-fallure (fsdile-error) Condition 

This condition name signifies a problem with the file operation requested. It is an 
alternative to fs:file-request-failure (page 609), which means that the file system was 
unable to consider the operation properly. 

All the following conditions in this section are always accompanied by fs:file-operation- 
failure, fs:file-error, and error, so they will not be mentioned. 

fsrflle-open-for-output Condition 

'Ibc request cannot be performed because the file is open for output 
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fsrfila-locked Condiiion 

Hie file cannoi be accessed because it is already being accessed. Just which kinds of 
simultaneous access are allowed depends on the file system. 

fs:circular-11nk Condiiion 

A link could not be opened because it pointed, directly or indirectly through other links, 
to itself. In fact, some systems report this condition whenever a chain of links exceeds a 
fixed length. 

fs: invalld-byte-slra Condiiion 

In open, tlic specified byte size was not valid for the particular file server or file. 

fs: no-moPe-room Condiiion 

PoKessing a request requires resources not available, such as space in a directory, or free 

disk blocks. 

fs:f llapos-out-of-ranga Condiiion 

'Ihe :set-pointer operation was used with a pointer value outside the bounds of the file. 

fs:not-ava1 labia Condiiion 

A requested pack, file, etc. exists but is currently off line or not available to users. 

fstflle-lookup-arrop Condition 

This condition name categorizes all sorts of failure to find a specified file, for any 
operation. 

ts!dev1ce-not-found (fs:file-lookup-error) Condiiion 

The specified device does not exist. 

fs:d1pectory-not-found (fs:file-lookup-error) Condition 

The specified directory does not exist. 

fstfUe-not-found (fs:file-lookup-error) Condition 

There is no file with the specified name, type and version. This implies that the device 
and directory do exist, or one of the errors described above would have been signaled. 

fstmultlple-flle-not-found (fs:file-lookup-error) Condiiion 

There is no file with the specified name and any of the specified types, in with-open- 
file-search. Three special operations are defined: 

loperation Returns tlie function which used with-open-file-search, such as load. 

:pathname "Fhe base pathname used. 

ipathnames A list of all the pathnames that were looked fisr. 

fs:11nk-target-not-found (fs:flle-lookup-error) Condition 

The file specified was a link, but the link’s target filename fails to be found. 
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fs: access-error Condition 

riic operation is possible, but the file server is insubordinate and refuses to obey you. 

fs: incorrect-access-to-fHe (access-error). Condition 

fs:incorrect-access-to-d1rectory (access-error). Condition 

The file server refuses to obey you because of protection attached to the file (or, the 

directory). 

fs; Inval Id-wildcard Condition 

A pailinaine had a wildcard in a place where the particular file server docs not support 

ilicni. Such pathnames are not created by pallinaipc parsing, but they can be created 
with the :new-pathname operation. 

fs :w11dcard-not-a11owed Condition 

A pathname with a wildcard was used in an operation tliat docs not support it. For 
example, opening a file with a wildcard in its name. 

fs :wrong-k1nd-of-f lie Condition 

An operation was done on the wrong kind of file. If files and directories share one name 
space and it is an error to open a directory, the error possesses this condition name. 

fs:craat1on-fa1lure Condition 

An attempt to create a file or directory failed for a reason specifically connected widi 
creation. 

fs:f1le-already-ex1sts (fsrereatiort-failure) Condition 

The file or directory to be created already exists. 

fstsuperior-not-directory (fsxreation-failure fsiwrong-kind-of-file) Condition 

In file systems where directories and files share one name space, this error results from an 
attempt to create a file using a filename specifying a directory whose name exists in the 
file system but is not a directory, 

fs;del6te-fa1lupe Condition 

A file to be deleted exists, but for some reason cannot be deleteti. 

fs:d1rectopy-not-empty (fs:delete-failure) Condition 

A file could not be deleted because it is a directory and has files in it. 

fs:dont-del 0 te-flag-set (ts;delete-failure) Condition 

A file could not be deleted because its “don’t delete” flag is set 

fs: pename-fallupe Condition 

A file to be renamed exists, but the renaming could not be done. The :new-pathname 
operation on the condition instance returns tlie specified new pathname, which may be a 
pathname or a string. 
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fs:rename-to-exist1ng-file (fsirename-failure) Condition 

Renaming cannot b^dotte because tlicrc is already a file with the specified new name. 

fs:r«name-acPoss-d1 rectories {fs;rename-failiire) Condition 

Renaming cannot be done because the new pathname contains a diflerent device or 
directory from the one the file is on. This may not always be an error—some file systems 
support it in certain cases—but when it is an error, it has tliis condition name. 

fs:unknown-property (fs:change-property-failure) Condition 

A property name specified in a :change-properties operation is not supported by the file 
server. (Some file servers support only a fixed set of property names.) I’he rproperty 
operation on die condition insunicc returns the problematical property name. 

fs:invalid-property-value (fsxhange-property-failure) Condition 

In a :change-properties operation, some property was given a value tliat is not valid for 
it. 'I’hc property operation on die condition instance returns the property name, and the 
;value operation returns the specified value. 

fs:Invalid-property-name (fsxhange-property-failure) Condition 

In a xhange-properties operation, a syntactically invalid property name was specified, 
lliis may be because it is too long to be stored. I’he property operation on the 
condition instance returns the property name. 

25.8 File Servers 

Files on remote file servers are accessed using file severs over the Chaosnet. Normally 
connections to servers are established automatically when you try to use them, but there are a few 
ways you can interact with them explicitly. 

When characters are written to a file server computer that normally uses the ASCII character 
set to store text. Lisp Machine characters are mapped into an encoding that is reasonably close to 
ah ASCII transliteration of the text. When a file is written, the characters are converted into this 
encoding; the inverse transfonnation is done when a file is read back. No information is lost. 
Note that the length of a file, in characters, is not the same measured in original Lisp Machine 
characters as it is measured in the encoded ASCII characters. In the currently implemented 
ASCII file servers, the following encoding is used. All printing characters and any characters not 
mentioned explicitly here are represented as themselves. Codes 010 (lambda). Oil (gamma), 012 
(delta), 014 (plus-minus), 015 (circle-plus), 177 (integral), 200 through 207 inclusive, 213 (Delete), 
and 216 and anything higher, are preceded by a 177; that is, 177 is used as a quoting character 
for these codes. Codes 210 (Overstrike), 211 (Tab), 212 (Line), and 214 (Page), arc converted 
to their ASCII cognates, namely 010 (backspace), 011 (horizontal tab), 012 (line feed), and 014- 
(form feed) respectively. Code 215 (Return) is converted into 015 (carriage return) followed by 
012 (line feed). Code 377 is ignored completely, and so cannot be stored in files. 

When a file server is first created, for you on a particular host, you must tell the server how 
to log in on that host. This involves specifying a username, and, if the obstructionists are in 
control of your site, a password, ITie Lisp Machine prompts you for these on the terminal when 
they are needed. 
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logging in a file server is mu the same thing as logging in on ilic Lisp Machine (sec login, 
page 801). The latter identifies you as a user in general and involves specifying one host, your 
login host. The former identifies you to a particular file server host and must be done for each 
host on which you access files. However, logging in on the Lisp Machine docs specify the 
username for your login host and logs in a file server there. 

The Lisp Machine uses your username (or the part tliat follows the last period) as a first 
guess for your password (this happens to take no extra time). If tliat does not work, you arc 
asked to type a password, or else a username and a password, on the keyboard. You do not 
have to give tlic same user name that you arc logged in as, since you may have or use different 
user names on different machines. 

Once a password is recorded for one host, tlie system uses that password as tlic guess if you 
connect to a file server on another host. 

fstuser-unamas Variable 

ITiis is an alist matching host names with the usernames you have specified on those 
hosts. Kiich element is tlic cons of a host object and tlic username, as a string. 

For hosts running ITS, tlic symbol fs;its is used instead of a host object. 'Phis is because 
every user has die same username on all ITS hosts. 

fs:user-host-password-a11st Variable 

Once you have specified a password for a given username and host, it is remembered for 
the duration of the session in this variable. I'ht; value is a list of elements, each of the 
form 

((username host name) password) 

All three data are strings. 

The remembered passwords arc used if more than one file server is needed on the same host, 
or if tlic connection is broken and a new file server needs, to be created. 

If you are very scared of your password being known, you can turn off the recording by 
setting this variable: 

fs:pecord-passwords-flag Variable 

Passwords arc recorded when typed in if this variable is non-nil. 

You should set the variable at the front of your init file, and also set fs:user-host- 
password-alist to nil, since it will already have recorded your password when you logged in. 

If you do not use a file server for a period of time, it is killed to save resources on the 
server host. 

fs:host-un1t-11fet1m0 Variable 

Ihis is tlic length of time after which an idle file server connection should be closed, in 
60ths of a second. The default is 20 minutes. 
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Some hosts have a caste system in which ail users are in)t equal, it is sometimes necessary to 
enable one’s privileges in order to exercise them. This is done with tlicse functions: 

fs:enable-capabi11t1es /««/ &rcst capabilities 

Ivnablcs the named capabilities on file servers for the specified host, capabilities is a list of 
strings, whose meanings depend on the particular file system that is available on host. If 
capabilities is nil, a default list of capabilities is enabled; the default is also dependent on 
the operating system type. 

fs:d1sable-capabilities host &rcst capabilities 

Disables the named capabilities on file servers for the specified host, capabilities is a list 
of strings, whose meanings depend on the particular file system that is available on host. 
If capabilities is nil. a default list of capabilities is disabled; the default is also dependent 
on the operating system type. 

'Hic PHMK utility has a mode that displays the status of all your file connections, and of the 
host unit data structures that record them. Clicking on a connection with tlie mouse gets a menu 
of operations, of which die most interesting is reset. Resetting a host unit may be useful if tlie 
connection becomes hung. 


25.8.1 Errors in Communication with File Servers 

fstflle-request-fallure (fs:file-error error) Condition 

I’his condition name categorizes errors that prevent the file system from processing the 
request made by the program. 

The following condition names are always accompanied by the more general classifications 

fs:file-request-failure, fs:file-error, and error. 

fsrdata-error Condition 

This condition signifies inconsistent data found in the file system, indicating a failure in 
the file system software or hardware. 

fsthost-not-avallable Condition 

ITiis condition signifies that the file server host is up, but refusing connections for file 
servers. 

fs:network-1ossage Condition 

This condition signifies certain problems in the use of the Chaosnet by a file server, such 
as failure to open a data connection when it is expected. 

fs:not-enough-resources Condition 

This condition signifies a shortage of resources needed to consider processing a request, as 
opposed to resources used up by the request itself. This may include running out of 
network connections or job slots on the server host. It does not include running out of 
space in a directory or running out of disk space, because these are resources whose 
requirements come from processing the request 
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fs:unknown-operation 


Condilion 


I'liis condition signifies ihnt the piirticular file system fails to implement a standardly 
defined operation; such as, expunging or undeletion on I'l’S. 
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26. The Chaosnet 

I'hc purpose of the basic software protocol of Chaosnet is to allow high-speed communication 
among processes on different machines, with no undetected transmission errors. 


26.1 Cliao.sncl Overvieir 

The principal service provided by Chaosnet is a conncclion between two user processes. ’ITiis 
is a full-duplex reliable packet-transmission channel. The network undertakes never to garble, 
lose, duplicate, or resequence die packets; in tlie event of a serious error it may break the 
connection otf entirely, informing both user pixK'esses. User programs may deal explicitly in tenns 
of packets. - They may also ignore packet boundaries and treat tlic connection as two uni¬ 
directional streams of 8-bit or 16-bit bytes, but this really works by means of packets. 

If you just want to ask a question of another process or host and receive a reply, you can use 
a simple transaction: You send only one packet to the other host, and it sends one packet back. 
This is more efficient than establishing a connection and using it only briefly. In a simple 
transaction, tlic server cannot tell whether the user received the answer: and if the user does not 
receive the answer, it cannot tell whether tlte server received tlie question. In fact, the server 
might receive the question more titan once. If this is unacceptable, a connection must be used. 

Each node (or host) on the network is identified by an address, which is a 16-bit number. 
ITicse addresses are used in the routing of packets. 'ITicre is a table (the system host table, SYS: 
CHAOS; HOSTS TXT) tliat relates symbolic host names to numeric host addresses. The host 
table can record addresses on any number of different networks, and in certain contexts a host 
address is meaningful only together with the name of the network it is for. 

The data transmitted over connections are in units called packets. Each packet contains an 8- 
bit number, the opcode, which indicates what its function is. Opcode numbers arc always given 
in octal. Opcodes less than 200 (octal) are special purpose. Each such opcode that is used has an 
assigned name and a specific function. Users need not know about all of them. Opcodes 200 
through 277 (octal) arc used for 8-bit user data. Opcodes 300 through 377 (octal) are used for 16- 
bit user data. 

Each packet also contains some number of data bytes, whose meaning depends on the opcode. 
If the opcode is for user data, then it is up to tlic application user software to decide on the 
interpretation. 

Establishing a connection: 

A connection is created because one process sends a request to a host. The request is a 
packet containing the special-purpose opcode RFC. The data contains a contact name which is 
used to find the process to connect to. 'fhere may be a process on the target host listening on 
this contact name. If so, it decides whether to agree to the connection. Alternatively, the contact 
name can be the name of a standard service such as TELNET. In this case, the receiving host 
creates a process to respond, loaded witli the program for that service. 
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Once a connection has been established, llierc is no more need for tlie contact name and it is 
discarded. The I.isp Machine remembers what contact name was used to open a connection, but 
this is only for the user’s information. 

In the, ease where two existing pr(x;esses tliat already know about each other want to establish 
a connection, they inust agree on a contact name, and then one of them must send the request 
while the other listens. They must agree between themselves which is to do which. 

Contact names arc restricted to strings of upper-ease letters, numbers, and ASCII punctuation. 
The maximum length of a contact name is limited only by the packet size, altliough on ITS hosts 
the names of automatically-started servers arc limited by tlic file-system to six characters, 'fhe 
contact name is tenninated by a space. If the Rl-C packet contains data beyond tlie contact 
name, it is just for interpretation by the listening process, which can also use it in deciding 
whether to accept the connection. 

A simple transaction is also begun with an RFC packet. There is nothing in the RFC packet 
which indicates whether it is intended to start a connection or a simple transaction. The server 
has die option of doing citlicr one. Rut normally any given server always does one or tlie other, 
and the requestor knows which one to expect. 

'fhe server accepts the request for a connection by sending an OPN packet (a packet with 
opcode OPN) to the requestor. It can also refuse tlie connection by sending a CLS packet. The 
daUi in the Cl.S packet is a string explaining the reason for the refusal. Another alternative is to 
tell die requestor to try a different host or a different contact name. This is called forwarding the 
request, and is done with a FWD packet. 

The server can also respond with an answer, an ANS packet, which is the second half of a 
simple transaction. (Refusing and forwarding are also meaningful when a simple transaction is 
intended, just as when a connection is intended). 

Once the connection is open: 

Data transmitted dirough Chaosnet generally follow Lisp Machine standards. Bits and bytes 
arc numbered from right to left, or least-significant to most-significant. The first 8-bit byte in a 
16-bit word is die one in the arithmetically least-significant position. The first 16-bit word in a 

32-bit double-word is die one in the arithmetically least-significant position. This is the “little- 

endian” convention. 

Big-endian machines such as the PDP-10 need to reorder the characters in a word in order to 
access diem conveniently. For their sake, some packet opcodes imply 8-bit data and some imply 
16-bit data. Packets known to contain 8-bit bytes, including opcodes 200 dirough 277, are stored 

in the big-endian machine’s memory a character at a time, whereas packets containing 16-bit data 

are stored 16 bits at a time. 

The character set used is dictated by the higher-level protocol in use. Telnet and Supdup, for 
example, each specifics its own ASCII-based character set. The default character set—used for 
new protocols and for text that appears in the basic Chaosnet protocol, such as contact names—is 
die Lisp Machine character set 
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If one process tries to send data faster Uian the other can prtKcss it, the biincred packets 
could devour lots of ineinory. PreventitTg- this is the purpose of flow amlml. Mach priKCSS 
specifics a window size, which is the number of packets that are allowed to be waiting for dial 
priKcss to read. Attempting to send on ;i connection whose other side's window is full waits until 
Ute other side reads some ptickets. The default window size is 13, but for some applications you 
might wish to specify a larger value (see chaosxonnect, page 615). I'here is little reason ever to 
specify a smaller value. 

Breaking a connection: 

Kitlier end of a connection can break the connection abruptly by sending a CI.S packet. The 
data in this packet is a string describing why tlie connection was broken. 

I'o break a connection gently, it is necessary to verify that all the data transmitted was 
received properly before sending a CI S. This matters in some applications and is unnecessary in 
others. When it is needed, it is done by sending a special packet, an M'OF packet, which is 
mostly like a data packet except for its significance with regard to closing die connection, fhe 
EOl-' packet is like the words “the end” at the end of a book: it tells the recipient that it has 
received all die data it is supposed to receive, that there are no missing pages that should have 
followed. When die sender of the HOF secs the acknowledgement for the l:'.OF packet, indicating 
that the EOF was received and understood, it can break die connection with a CLS. 

If a process that expects to receive an EOF gets a CLS with no EOF, it takes diis to mean 
that die connection was broken before the transmission was finished. If the process docs receive 
an EOF, it does not break the connection itself immediately. It waits to see the sender of the 
EOF break it. If this does not happen in a few seconds, the EOF recipient can break the 
connection. 

It is illegal to put data in an EOF packet; in other words, die byte count should always be 
zero. Most Chaosnet implcmentaUons simply ignore any data that is present in an EOF. 

If both sides are sending data and both need to know for certain where “the end” is, they 
must do something a little more complicated. Arbitrarily call one party the user and the other the 
server. I'he protocol is that after sending all its data, each party sends an EOF and waits for it 
to be acknowledged. The server, having seen its EOF acknowledged, sends a second EOF. The 
user, having seen its EOF acknowledged, looks for a second EOF and then sends a CLS and 
goes away. The server goes away when it sees the user’s CLS, or after a brief timeout has 
elapsed. This asymmetrical protocol guarantees that each side gets a chance to know that both 
sides agree that all the data have been transferred. The first CLS is sent only after both sides 
have waited for their (first) EOF to be acknowledged. 

Clearing up inconsistencies: 

If a host crashes, it is supposed to forget all the connections that it had. When a packet 
arrives on one of the former connections, the host will report “no such connection” to tlie sender 
with a LOS packet, whose data is a string explaining what happened. 'I'he same thing happens if 
a CLS packet is lost: tlie intended recipient may keep trying to use tlie connection that the other 
side (which sent the CLS) no longer believes should exist. LOS packets are used whenever a host 
receives a packet that it should not be getting; the recipient of the LOS packet knows that the 
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connection it thought it was using docs not exist any more. 

26.2 Conns 

On the Lisp Machine, your handle on a connection is a named structure of type chaos:conn. 
The conn may have an actual connection attached to it, or it may have a connection still being 
made, or record that a connection was refused, closed or broken. 

chaos:inactive-state 

This conn is not really in use at all. 

eh aosirfe-sent-state 

This conn was used to request a connection to another prcKCSs, but no reply has 
been received. When the reply is received, it may change the conn’s state to 
chaos.answered-state, chaos:cls-received-state, or chaos:open-state. 

chaos:listening -state 

This conn is being used to listen witli. If a RFC packet is received for the 
contact name you arc listening on, the state changes to chaos:rfc-received-state. 

chaos:rfc-received-state 

This means tliat your listen has “heard” an RFC packet tliat matches it. You can 
accept reject, forward or answer the request. Accepting goes to state 
chaos:open-state; refusing or forwarding goes to to state chaos:inactive-state. 

chaosropen-state 

'ITiis conn is one end of an open connection. You can receive any data packets 
that are waiting and you can transmit data. 

chaos:answered-state 

This conn was used to send an RFC packet and an ANS packet was received in 
response (a simple transaction answer arrived). You can read the ANS packet, 
that is all. 

chaos:cls-received-state 

This conn has received a CLS packet (the connection was closed or refused). 
You can read any data packets that came in before the CLS; after them you can 
read the CLS. 

chaos:los-received-state 

This conn’s connection was broken and the other end sent a LOS packet to say 
so. 'Hie LOS packet is the only packet available to be read, 

chaos:host-down-state 

Ihe host at tlie other end of this conn’s connection has not responded to 
anything for a significant time. 

chaosdoreign-state 

The connection is being used with a foreign protocol encapsulated in UNC packets 
(sec the MIT A1 Lab memo entitled “Chaosnet” for more infonnation on this). 

llicse are the fields of a conn that you might be interested in: 
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chaos:conn-state conn 

lliis slot holds tlic suite of conn. It is one of the symbols listed tibovc. 

chaos:conn-fore1gn-address conn 

Returns the address of the host at the other end of tliis connection. Use si:get-host- 
from-address to find out which host this is (see page 577). 

chaos:conn-read-pkts conn 

Internttlly threaded chain of incoming packets avttilablc to be rettd from conn. 

Its main use for the applications programmer is to test whether lltcrc arc any incoming 
packets. 

chaos:conn-w1ndow-ava11ab1e conn 

Returns tlic number of packets you may transmit before the network software forces you 
to wait for the receiver to read some, This is just a minimum. By the time you actually 
send Uiis many packets, tlic receiver tnay already have sttid he has room for some more. 

chaos:conn-pi 1st conn 

’I’his slot is used to store arbitrary properties on conn. You can store properties yourself; 
use property names that are not in the chaos package to avoid conflict. 

chaos:contact-name conn 

Returns the contact name with which conn was created. ITic contact name is not 
significant to the functioning of the connection once an RFC and LSN have matched, but 
it is remembered for the sake of debugging. 

chaos:wait conn stale timeout &optional whostate 

Waits until the state of conn is not die symbol state, or until timeout 60ths of a second 
have elapsed. If the timeout occurs, nil is returned; otherwise t is returned, whostate is 
the process state to put in the who-line; it defaults to "Chaosnet wait", 

26.3 Opening and Closing Connections 
26.3.1 User-Side 

chaos:connect host contact-name «fcoptional window-size timeout 

Opens a stream connection; returns a conn if it succeeds or else a string giving the 
reason for failure, host may be a number or the name of a known host, contact-name is 
a string containing the contact name and any additional arguments to go in the RFC 
packet. If window-size is not specified it defaults to 13. If timeout is not specified it 
defaults to 600 (ten seconds). 
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chaos:simple hosi comaei-mime &opiional timeout 

Taking arguments similar to those of chaosxonnect, this performs tlic user side of a 
simple-transaction. The returned value is eiUier an ANS packet or a string containing a 
failure message. The ANS packet should be disposed of (using chaos:return-pkt, see 
below) when you are done with it. 

chaos:remove-conn conn 

Makes eoim null and void. It becomes inactive, all its buffered packets are freed, and the 
corresponding Chaosnet connectit)n (if any) goes away. This is called removing tlte 
connection, m/// itself is marked for reuse for another Chaosnet connection, so you 
should not do anything else with it after it is removed. 

chaos:close-conn conn &optional reason 

Closes and removes the connection. If it is open, a CLS packet is sent containing the 
string reason. Don't use tliis to reject RFC’s; use chaos;reject for that. 

chaos:open-foreign-connection host index &optional pkt-allocation distinguished-port 

Creates a conn that may be used to transmit and receive foreign protocols encapsulated in 
UNC packets, host and index arc the destination address for packets sent with 
chaos.send-unc-pkt. pkt-allocation is the ‘window size’, i.e. the maximum number of 
input packets that may be buffered. It defaults to 10. If distinguished-port is supplied, 
tlic local index is set to it. Hiis is necessary for protocols tliat define the meanings of 
particular index numbers. 

Sec the MIT AI Lab memo entitled “Chaosnet” for more information on using foreign 
prottKols. 

26.3.2 Server-Side 

chaos:listen contact-name &optional window-size wait-for-rfc 

Waits for an RFC for tlie specified contact name to arrive, then returns a conn that is in 
chaos:rfc-received-state. If window-size is not specified it defaults to 13. If wail-forrfc 
is specified as nil (it defaults to t) then the conn is returned immediately without waiting 
for an RFC to arrive. 

chaos :sepvep-a11st Variable 

Contains an entry for each server that always exists. When an RFC arrives for one of 
tlicse servers, the specified form is evaluated in the background process; typically it 
creates a process that will then do a chaos:listen. Use the add-initialization function to 
add entries to this list 

chaos:accept conn 

conn must be in chaosrrfc-received-state. An OPN packet is transmitted and conn 
enters tlic chaosxpen-state. If the RFC packet has not already been read with 
chaos:get-next-pkt, it is discarded. You should read it before accepting, if it contains 
arguments in addition to the contact name. 
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chaos: reject <w;« mtson 

conn must be in chaos:rfc-received-state. A CLS packet containing the string reason is 
sent and conn is removed from the connection Uible. 

chaos;forward-all coniaci-name host 

Causes all future requests for connection to tliis host on contact-name to be forwarded to 
the same contact ninue at host host. 

chaos:answer-string conn siring 

conn must be in chaos;rfc-received-state. An ANS packet containing the string siring 
is sent and conn is removed from die connection Uible. 

chaos:answer conn pki 

conn must be in chaos;rfc-received-state, pkl is transmitted as an ANS packet and 
conn is removed. Use this function when the answer is some binary data rather tlian a 
text string. 

chaos:fast-answer-str1ng contact-name string 

If a pending RFC exists to contact-name, an ANS containing string is sent in response to 
it and t is returned. Otherwise nil is returned. I'his fimetion involves the minimum 
possible overhead. No conn is created. 

26.4 Stream Input and Output 

chaos:open-stream host contact-name &key window-size timeout error direction characters 
ascii-translation 

Opens a Chaosnet connection and returns a stream that does I/O to it. host is the host to 
connect to; contact-name is the contact name at that host. These two arguments are 
passed along to chaos:connect. 

If host is nil, a connection to contact-name is listened for, and a stream is returned as 
soon as a request comes in for that contact name. At this time, you must accept or reject 
the connection by invoking the stream operation :accept or :reject. Before you decide 
which to do, you can use the foreign-host operation to find out where the connection 
came from. 

The remaining arguments are: 
window-size 

timeout These two arguments specify two arguments for chaos:connect. 

error If the value is non-nil, a failure to connect causes a Lisp error. 

Otherwise, it causes a string describing the error to be returned. 

direction 

characters 

ascii-translation 

These three arguments are passed along to chaos:make-stream. 


PS:<L.MAN>CHAOS.'IEXT.25 


8-JUN-84 



Siroiiin Input ;ind Output 


618 l.isp Machine Miinuitl 


chaos:make-stream conn &kcy direction characters ascii-translation 

Creates and returns a stream that does I/O on the connection conn, which should be 
open as a stream connection, direction may be :input, :output or :bidirectional. 

If characters is non-nil (which is tlic dcftiult), ibe stream reads and writes 8-bit bytes. If 
characters is nil. die stream reads and writes 16-bit bytes. 

If aseii-translation is non-nil, characters written to tlic stream are translated to standard 
ASCII before they are sent, and characters read are translated from ASCII to the Lisp 
Machine character set. 

: foreign-host wichaostbasic-stream 

Returns the hr)st object for the host at the other end of tliis stream’s connection. 

: accept Opemr/o //oh chaosibasic-stream 

Accepts the request for a connection which this stream received. Used only for streams 
made by chaos:open-stream with nil as the host argument. 

: reject reason-string Opcation onchaos:basic-s\ream 

Rejects the request for a connection which this stream received, sending reason-string in 
the CLS packet as the reason. Used only for streams made by chaos:open-stream with 
nil as the host argument. 

:close &optional abort-p Opeaot/o/jo«chaos:basic-stream 

Sends a Cl-S packet and removes tlic connection. For output connections and 
bidirectional connections, the :eof operation is perfonred first, if abort-p is nil. 

:force-output Y/pera/ /oh oh chaos:basic-output-stream 

Any buffered output is transmitted. Normally output is accumulated until a full packet’s 
worth of bytes are available, so that maximum-size packets are transmitted. 

; f 1 n 18h Operation on chaos:basic-output-stream 

Waits until either all packets have been sent and acknowledged, or the connection ceases 
to be open, if successful, returns t; if the connection goes into a bad state, returns nil. 

: eof Operation on chaos:basic-output-stream 

Forces out any buffered output, sends an EOF packet, and does a :finish. 

:cleap-eof Opcra//oHO'jchaos:basic-input-stream 

Allows you to read past an HOF packet on input. Normally, each :tyi done at eof returns 
nil or signals the specified eof error. If you do :clear-eof on the stream, you can then 
read more data (assuming there are data packets following the EOF packet). 
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26.5 Packet I npui and Output 

Input and output on a Chaosnet connection can be done at tltc whole-packet level, using the 
functions in this section. A packet is represented by a chaos:pkt data structure. Allocation of 
pkts is controlled by the system; each pkt diat it gives you must be given back. Ihcre are 
functions to convert between pkts and strings. A pkt is an art-16b array containing the packet 
header and daut; Uie leader of a pkt contains a number of fields used by the system. 

chaos :f1rst-data-word-in-pkt Constant 

This is die index in any pkt of the element dial is die fiiiit 16-bit word of user data. 
(Preceding elements arc used to store a header used by die hardware.) 


chaosrraax-data-words-per-pkt 

flic maximum number of 16-bit data words allowed in a packet. 


Constant 


chaos :plct-opcode pkt 

Accessor for the opcode of the packet pkt. To set die opcode, do 
(self (chaos;pkt-opcode my-pkt) my-opcode) 

The system provides names for all die opcodes standardly used. The names useful to the 
applications programmer appear at the end of this sccdon. 

chaos :plct-nbytos pkt 

Accessor for the number-of-data-bytes field of pkCs. I’his field says how much of pkt s 
conicets arc valid data, measured in 8-bit bytes, fhis field can be set with setf also. 

Chaos:pkt-str1ng pkt . . r u- 

An indirect array that is the data field of pkt as a string of 8-bit bytes. Fhe length of this 

string is equal to (chaos:pkt-nbytes pkt). If you wish to record the contccts of pkt 
permanently, you must copy this string. 

chaos :set-pkt-str1ng pkt &rcst strings 

Copies the strings into the data field of pkt, concatenating them, and sets (chaos.pkt~ 

nbytes pkt) accordingly. 

chaos:get-pkt 

Allocates a pkt for use by the user, 
chaos:return-pkt pkt 

Returns pkt to the system for reuse. The packets given to you by chaos:get-pkt, 
chaos:get-next-pkt and chaos:simple should be returned to the system in this way 
when you are finished with them. 

chaos:send-pkt conn pkt &optional (o/?cot/echaos:dat-op) 

Transmits pkt on conn, pkt should have been allocated with chaos:get-pkt and then had 
its data field and n-bytes filled in. opcode must be a data opcode (#o200 or more) or 
EOF. An error is signaled, with condition chaos:not-open-state, if conn is not open. 

Giving a pkt to chaos:send-pkt constitutes giving it back to the system. You do not 
need to call chaos:return-pkt. 
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chaos: send-strlng conn &rcst strings 

Sends a data packet containing the concatenation of strings as its datit. 

chaos:send-unc-pkt conn pkl &optional pkl-number ack-number' 

Transmits pkt, an UNC packet, on conn. I'hc opcode, packet number, and acknowledge 
number fields in the packet header arc filled in (the latter two only if the optional 
arguments are supplied). 

See tlte MIT Al I,ab memo entitled “Chaosnet" for more information on using foreign 
protiKols. 

chaosimay-tpansmlt conn 

A predicate that returns t if tliere is any space in the window for transmitting on conn. 

If the value Is nil, you may have to wait if you try to transmit. If the value is t, you 

certainly do not have to wait. 

chaos:f1nish-conn conn &optional "NetFinish") 

Waits until eitlier all packets have been sent and acknowledged, or the connection ceases 

to be open. If successful, returns t; if tlie connection goes into a bad state, returns nil, 

whostate is the priKess state to display in tlie who-line while waiting. 

chaos:conn-fin1shed-p conn 

t unless conn is open and has sent packets which have not been acknowledged. 

chaos:get-next-pkt conn &optional (no-hang-pni\} whostate check-conn-state 

Returns the next input packet from conn. When you are done with tlie packet you must 
give it back to the system with chaos:return-pkt. This can return an RFC, CLS, or 
ANS packet, in addition to data, UNC, or HOF, 

If no packets are available, nil is returned if no hang-p is t. Otherwise, chaos:get-next- 
pkt waits for a packet to come in or for tlie state to change, whostate is displayed in the 
who line; it defaults to "Chaosnet Input". 

If check-conn-state is non-nil, the connection state is checked for validity before anything 
else is done, and an error is signaled if the connection is in a bad state, with condition 
name chaos:host-down, chaos:los-received-state, or chaos:read-on-closed- 
connection. If check-conn-state is nil and no-hang-p is t, nil is returned, check-conn-state 
defaults to (not no-hang-p). 

chaos:data-ava11ab1e conn 

A predicate that returns t if there any input packets available from conn. 
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Here are symbulic names fur the opeodes tliat an applications pnigrammcr needs to know about: 

chaos :rfc-op Consfant 

This special-purpose opcode is used for requesting a connection. 'I'he data consists of the 
contact name tcmiinatcd by a space character, followed optionally by additional data 
whose meaning is up to the server for tliat contact name. 

chaos :1sn-op Comiani 

This special-purpose opcode is used when you ask to listen on a contact name. The data 
is just the contact name. This packet is never actually sent over the network. Just kept in 
the Chaosnet software and compared with the contact names in RI-'C packets that arrive. 

chaos: op n-op Comtant 

I'his special-purpose opcode is used by the server pnKcss to accept the request for a 
connection conveyed by an RFC packet. Its data serves only internal functions. 

chaos :ans-op Constant 

lliis special-purpose opcode is used to send a simple reply. 'Hie simple reply is sent back 
in place of opening a connection. 

chaos :1os-op Constant 

I'his special-purpose packet is what you receive if you try to use a connection that has 
been broken. Its daui is a message explaining the situation, which you can print for the 
user. 

chaos: cl s-op Constant 

'I'his special-purpose packet is used to close a connection. Its data is a message explaining 
tlie reason, and it can be printed for the user. Note that you cannot count on receiving a 
CLS packet because it is not retransmitted if it is lost. If tliat happens you get a LOS 
when you try to use the connection (thinking it is still open). 

CLS packets are also used for refiising to open a connection in the first place. 

chaos :eof-op Constant 

This special-purpose opcode is used to indicate the end of the data that you really want to 
transmit. When this packet is acknowledged by the other process, you know that all the 
real data was received properly. You can wait for this with chaos:finish. The EOF 
packet carries no data itself. 

chaos :dat-op Constant 

'This is opcode 200 (octal), which is the normal opcode used for 8-bit user data. Some 
protocols use multiple data opcodes in the range 200 through 277, but simple protocols 
that do not need to distinguish types of packets just use opcode 200. 
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26.6 Connection Inferrupls 

chaos:interrupt-function conn 

This attribute of a conn is a function to be called when certain events (Kcur on this 
connection. Nomially tliis is nil, which means not to call any function, but you can use 
setf to store a function here. Since the function is called in tlie Chaosnet background 
process, it should not do any operations that might have to wait for tlie network, since 
diat could pennanently hang the background prixess. 

The function’s first argument is one of the following symbols, giving tlie reason for the 
interrupt. The function's second argument is conn. Additional arguments may be present 
depending on tlie reason. The possible reasons arc: 

:input A packet has arrived for the connection when it had no input packets 

queued. It is now possible to do chaos:get-next-pkt without having to 
wait. I'hcrc arc no additional arguments. 

icotput An acknowledgement has arrived for the connection and made space in 

tlie window when formerly it was full. Additional output packets may 
now be transmitted with chaos Send-pkt without having to wait. There 
arc no additional arguments. 

:change-of-state 

The state of the connection has changed. The third argument to the 
function is the symbol for the new state. 

chaos:read-pkts conn 

Some interrupt functions want to look at the qiictied input packets of a connection when 
they get a :input interrupt. chaos:read-pkts returns the first packet available for reading. 
Successive packets can be found by following chaos:pkt-link. 

chaos:pkt-lInk pkt 

Lists of packets in the NCP arc threaded together by storing each packet in the 
chaos:pkt-link of its predecessor. The list is tenninated with nil. 

26.7 Chaosnet Errors 

sys: network-error (error) Condition Flavor 

All errors from tlie Chaosnet code use flavors built on this one. 
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26.7.1 Local Problems 

sys: local-network-error (sys;network-error error) CondUion Flavor 

I'his flavor is used for problems in connection with the Chaosnet that have entirely to do 
with what is going on in this Lisp Machine. 

sys rnetwork-resources-exhausted (ondiiion 

(sys:local-network-error sys:network-error error) 

Signaled when some local resource in tlie NGP was exhausted. Most likely, there are too 
many Chaosnet connections and tlic connection Uiblc is full. 


sys:unknown-address (sys:local-network-error sysmetwork-error error) Condition 

fhe address argument to chaos:connect or some similar function was not recognizable. 
I hc raddress operation on Uie condition instance returns the address that was supplied. 


26.7.2 Problems Involving Other Machines’ Actions 

sys : remoto-notwork-error (sysmetwork-error error) Condition Flavor 

'I'his flavor is used for network problems that involve the actions (or lack of them) of 
other machines. It is often useful to test for as a condition name. 


The operations connection and foreign-host return the chaosxonn object and the host 
object for the foreign host. 

All the condition names listed below imply the presence of sys:remote-network-error, 
sysmetwork-error and error. For brevity, these are not mentioned in the individual descriptions. 

Every instance of sys:remote-network-error is either a sysxonnection-error or a sys:bad- 
connection-state. 


sys;connect1on-eppor 

'I’his condition name categorizes failure to complete a connection. 


Condition 


sys: bad-connection-state Condition 

'This condition name categorizes errors where an existing, valid connection becomes 
invalid. 'The error is not signaled until you try to use the connection. 

sys;host-not-pespond1ng Condition 

'This condition name categorizes errors where no packets whatever arc received from the 
foreign host, making it seem likely that that host or the network is down. 

sys;host-not-pespond1ng-dup1ng-connect1on Condition 

(sysconnection-error sys:host-not-responding) 

'This condition is signaled when a host does not respond while it is being asked to make a 
connection. 
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sys :no-server-up (sysxonnection-error) Condition 

This condition is signaled by certain functions which request service from any available 
machine which can provide it, if no such machine is responding. 

sysihost-stopped-responding Condition 

(sys:bad-connection-state sys:host-not-responding) 

This condition is signaled when a host docs not respond even tliough a connection to it 
already exists. 

systconnectlon-rsfused (sysxonnection-error) Condition 

This is signaled when a connection is refused. 

ITie :reason operation on the condition instance: returns the reason specified in the CLS 
packet (a string) or nil if no reason was given. 

sys:connect1bn-c1osed (sys:bad-connection-state) Condition 

This is signaled when you try to send on a connection which has been closed by the 
other host. 

ITie :reason operation on the condition instance returns tlie reason specified in the CLS 
packet (a string) or nil if no reason was given. 

sys:connection-lost (sys:bad-connection-state) Condition 

Ihis is signaled when you try to use a connection on which a LOS packet was received. 

The :reason operation on the condition instance returns the reason specified in the CLS 
packet (a string) or nil if no reason was given. 

sys :connect1on-no-more-data (sys:bad-connection-state) Condition 

This is signaled when you try to read from a connection which has been closed by the 
other host, when there are no packets left to be read. (It is no error to read from a 
connection which has been closed, if you have not yet read all the packets which arrived, 
including the CLS packet). 

ITie ;reason operation on the condition instance returns the reason specified in the CLS 
packet (a string) or nil if no reason was given. 

26.8 Information and Control 

chaos :host-up-p host &optional {tiineouf\80.) 

t if host responds over the Chaosnet within timeout sixtieths of a second, otherwise nil. 
The value is always nil if host is not on the Chaosnet. 

chaos:up-hosts host-list &optional number-of-hosts {dmeout250.) 

Returns a list of all the hosts in host-list which are currently responding over the 
Chaosnet, host-list is a list of host names and/or host objects. 'ITie value is always a list 
of host objects, possibly nil for none of them. 
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W' nuinbcrof hosts is non-nil, it should be a positive inieger; when dial many hosts have 
responded, chaos:up-hosts returns right away without bothering to listen for replies from 
the rest. 

limeoui is an integer; if a host fails to respond for that many sixtieths of a second, it is 
assumed to be down. 

chaos:host-data &optional hosi 

host may be a number or a known host name, and defaults to the local host. Two values 
are returned. I'he first value is the host name and the second is tlie host number. If tlic 
host is a number not in the table, it is asked its name using the STATUS prottKol; if no 
response is received the name "Unknown" is returned. 

chaos;pr1nt-conn conn &optional (shorn) 

Prints everything the system knows about the connection. If short is nil it also prints 
everything die system knows about each queued input and output packet on the 
connection. 

chaos :pr1nt-ptct pkt &optional (s/jor/nil) 

Prints everything the system knows about the packet, except its data field. If short is t, 
only die first line of the information is printed. 

chaosrprlnt-all-pkts pkt &optional (shorit) 

Calls chaos:print-pkt on pki and all packets on the threaded list emanaUng from it. 

chaos:status 

Prints the hardware status. 

chaos:reset 

Resets the hardware and software and turns off Chaosnet communication. 

chaos:assure-enab1ed 

Turns on Chaosnet communication if it is not already on. It is normally always on unless 
you call one of the functions in this section. 

chaos tenable 

Resets the hardware and turns on Chaosnet communication. 

chaosrdlsable 

Resets the hardware and turns off Chaosnet communication. 

chaos:show-routing-table host &opdonal (s/reaw’standard-output) 

Print out host's routing table onto stream, 

chaos :show-rout1ng-path &key (from si:IocaI-host) to (s/rraw’standard-output) 

Show how a packet would get from from to to. For this to work when the hosts are oh 
different subnets, the bridge must respond to die DUMP-ROUTING-TABLE request. 
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The PHl'K program has a mode dial displays the status of all of the I.isp Machine's Chaosnet 
connections, and various other information, in a continuously updating fashion. 

26.9 I Uglier-Level Protocols 

I’his section briefly dtK'uments some of tlie higher-level protocols of the most general interest, 
riicre arc qtiitc a few other protocols which arc too specialized to mention here. All prottx:ols 
other titan the STATUS prottxtol are optional and arc only implemented by tliosc hosts that need 
them. All hosts are required to implement tlic STATUS protocol since it is used for network 
maintenance. 

The site files tell the Lisp Machine which hosts at your site implement certain higher-level 
protocols. See section 35.12, page 810. 

26.9.1 Status 

All network nodes, even bridges, arc required to answer RFC's with contact name STATUS, 
returning an ANS packet in a simple transaction. This protocol is primarily used for network 
maintenance. The answer to a STATUS request should be generated by the Network Control 
Program, rather tlian by starting up a server process, in order to provide rapid response. 


'The STATUS protocol is used to determine whether a host is up, to determine whether an 
operable path through the network exists between two hosts, to monitor network error statistics, 
and to debug new Network Control Programs and new Chaosnet hardware. The hostat function 
on the Lisp Machine uses tliis protocol. 


The first 32 bytes of the ANS contain the name of tlie node, padded on the right with zero 
bytes. I’he rest of the packet contains blocks of information expressed in 16-bit and 32-bit words, 
low byte first (little-endian convention). I'he low-order half of a 32-bit word comes first Since 
ANS packets contain 8-bit daui (not 16-bit), big-endian machines such as PDP-lOs have to shuffle 
the bytes explicitly when using this protocol. The first 16-bit word in a block is its identification. 
The second 16-bit word is the number of 16-bit words to follow. ITie remaining words in the 
block depend on the identification. 


I'his is the only block type currently defined. All items are optional, according to the count 
field, and extra items not defined here may be present and should be ignored. Note that items 
after the first two are 32-bit words. 

wordO A number between 400 and 777 octal. This is 400 plus a subnet number. This 

block contains information on this host’s direct connection to that subnet 

word 1 The number of 16-bit words to follow, uiiually 16, 

words 2-3 The number of packets received from this; subnet 


words 4-5 'I’he number of packets transmitted to this; subnet. 


words 6-7 


The number of transmissions to this sutinet aborted by collisions or because the 
receiver was busy. 
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words 8-9 


words 10-11 


words 12-13 


words 14-15 
words 16-17 


'Hie nmnber of incoming packets from lliis subnet lost because the lurst had not 
yet read a previous packet out of die interface and consequently die interface 
could not capture die packet. 

The number of incoming packets from diis subnet with CRC errors. These were 
either transmitted wrong or damaged in transmission. 

The number of incoming packets from diis subnet that had no CRC error when 
received, but did have an error after being read out of the packet bulTcr. This 
error indicates eidier a hardware problem with die packet buflci or an incorrect 
packet length. 

'The number of incoming packets from diis subnet diat were rejected due to 
incorrect length (typically not a multiple of 16 bits). 

The number of incoming packets from this subnet rejected for other reasons (e.g. 
too short to contain a header, garbage byte-count, forwarded too many times.) 


If word 0, die identification, is a number between 0 and 377 octal, diis is an obsolete fonnat 
of block. The idendfication is a subnet number and die counts arc as above except diat they are 
only 16 bits instead of 32. and consequently may overflow. This format should no longer be sent 
by any hosts. 


Identification numbers of 1000 octal and up arc reserved for future use. 


26.9.2 Routing Information 

For network and NCP debugging, this RFC/ANS protocol should be implemented. The 
contact name is DUMP-ROUTING-TABLE, and the response is an ANS packet whose words 
alternate contain a mcdiod to getting to a subnet, and the cost. If the method is zero, then the 
machine knows of know what to get to that subnet. If the mcdiod is positive and less than 400 
(octal), it is an interface of some kind to that subnet. If the method is 400 (octal) or greater, this 
is actually a bridge (host) off which the machine is bouncing packets destined for the subnet. 


26.9.3 Telnet and Supdup 

'The 'Telnet and Supdup protocols of the Arpanet exist in idendcal form in Chaosnet. These 
protocols allow access to a computer system as an interactive terminal from another network node. 

'The contact names arc TELNET and SUPDUP. 'The direct borrowing of the Telnet and 
Supdup protocols was eased by their use of 8-bit byte streams and of only a single connection. 
Note that these protocols define their own character sets, which differ from each other and from 
the Chaosnet standard character set 

For the Telnet protocol, refer to the Arpanet Protocol Handbook. For the Supdup protocol, 
sec MIT A1 l.ab memo 644, 

Chaosnet contains no counterpart of the INR/INS attention-getting feature of the Arpanet 
llic Telnet protocol sends a packet with opcode 201 octal in place of the INS signal. ITiis is a 
controlled packet and hence docs not provide the “out of band feature of the Arpanet INS, 
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however il is salisfaclory for tJie Telnet ‘interrupt process’ and ‘discard output’ operations on die 
kinds of hosts attached to Chaosnet. 

26.9.4 File Access 

'I’hc h’ll.F prohKol is primarily used by l isp Machines to access files on network file servers. 
ITS and TOPS-20 arc equipped to act as file servers. A user end for the file protocol also exists 
for rOPS-20 and is used for general-purpose file transfer. Tor complete documentation on the file 
proUKol, see SYS: DOC; FILE TEXT. The Arpanet file transfer protocols have not been 
implemented on tlic Chaosnet (except through the Arpanet gateway described below). 

26.9.5 Mall 

The MAIL proUKol Is used to transmit inter-user messages through tlie Chaosnet. The 
Aipanet mail protocol was not used because of its complexity and poor sutc of documentation. 
This simple protocol is by no means tlic last word in naail protocols; however, it is adequate for 
tlic mail systems we presently possess. 

The sender of mail connects to contact name MAIL and establishes a stream connection. It 
then sends the names of all the recipients to which th(; mail is to be sent at (or via) the server 
host. The names are sent one to a line and terminated by a blank line (two carriage returns in a 
row). The Lisp Machine character set is used. A reply (see below) is immediately returned for 
each recipient. A recipient is typically just the name of a user, but it can be a user-atsign-host 
sequence or anything else acceptable to the mail system on the server machine. After sending the 
recipients, the sender sends tlie text of the message, terminated by an EOF. After the mail has 
been successfully swallowed, a reply is sent. After the sender of mail has read the reply, both 
sides close the connection. 

In the MAIL protocol, a reply is a signal from the server to tlie user (or sender) indicating 
success or failure. 'I’he first character of a reply is a plus sign for success, a minus sign for 
permanent failure (e.g. no such user exists), or a percent sign for temporary failure (c.g. unable to 
receive message because disk is full). The rest of a reply is a human-readable character string 
explaining the situation, followed by a carriage return. 

The message text transmitted through the mail protocol normally contains a header formatted 
in the Arpanet standard fashion. Refer to the Arpanet Protocols Handbook. 
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26.9.6 Send 

'I'hc SKNl) proUK'ol is used to transmit an interactive message (requiring immediate attention) 
between users. I'hc sender connects to contact name SEND at the machine to which die recipient 
is logged in. The remainder of the RP'C packet contains die name of die person being sent to. 
A stream connection is opened and the message is transmitted, followed by an HOI'. Both sides 
close after following die end-of-data proUKol described in page 613. 'I'hc fact diat the RFC was 
responded, to affinnativcly indicates dtat the recipient is in fact present and accepting messages. 
I'hc message text should begin with a suitable header, naming die user that sent the message. 
I'hc standard for such headers, not currently adhered to by all hosts, is one line I'ormatted as in 
die following example: 

MooneMIT-MC 6/15/81 02:20:17 

Automatic reply to die sender can be implemented by searching for die first and using the 
SHNI) protocol to die host following the with die argument preceding it. 


26.9.7 Name 

'I'he Namc/Fingcr protocol of the Arpanet exists in identical fonti on the Chaosnet. Both 
l.isp Machines and timesharing machines support this protocol and provide a display of die user(s) 
currently logged in to them. 

The contact name is NAME, which can be followed by a space and a string of arguments like 
the “command line” of the Arpanet Name protocol. A stream connection is established and the 
“finger” display is output in Lisp Machine character set, followed by an EOF. 

Lisp Machines also support the FINGER protocol, a simple-transaction version of the NAME 
protocol. An RFC with contact name FINGER is transmitted and the response is an ANS 
containing the following items of information separated by carriage returns: the logged-in user ID, 
the location of the terminal, the idle time in minutes or hours-colon-minutes, the user’s full 
name, and the user’s group affiliadon. 

26.9.8 Time 

Ihe Time protocol allows a host such as a Lisp Machine that has no long-term timebase to 
ask the time of day. An RFC to contact name TIME evokes an ANS containing the universal 
time as a 32-bit number in four 8-bit bytes, least-significant byte first 


PS:<L.MAN>CHAOS.TEXT.25 


8-JUN-84 



1 liglicr-I .cvcl I’rolocols ()30 


I.isp M;iciiinc Manuai 


26.9.9 Uptime 

i'his is similar to the 'I'lMK protocol, except that the contact name is UPTIME, and the time 
returned is actually an interval (in seconds) describing how long the host has been up. 


26.9.10 Arpanet Gateway 

i'his proUKol allows a Chaosnet host to access almost any service on the Arpanet. 'ITic 
gateway server runs on each I TS host that is connected to both networks. It creates an Arpanet 
connection and a Chaosnet connection and forwards diita bytes from one to the other. It also 
provides for a one-way auxiliary connection, used for the daui connection of the Arpanet File 
Transfer Protocol. 

The RFC packet contains a contact name of TCP, a space, the name of the Arpanet host to 
be connected to, optionally followed by a space and tlie contact-scKket nuinber in (Ktal, which 
defaults to 1 if omitted, llie name of host can also be an Internet-format address. 'I’he bi¬ 
directional 8-bit connection is made by connecting to the host with I'CP. 

If a data packet with opcode 201 ({x:tal) is received, an Arpanet INS signal is transmitted. 
Any data bytes in this packet arc transmitted nonnally. ('I'his docs nothing in the current server, 
since I’CP docs not define an intcraipt signal.) 

If a data packet with opcode 210 (octal) is received, an auxiliary connection on each network 
is opened. I'he first eight data bytes are the Chaosnet contact name for the auxiliary connection; 
the user should send an RFC with this name to the server. The next four data bytes are the 
'fCP scKket number to be connected to, in tlie wrong order, most-significant byte first The byte- 
size of tlie auxiliary connection is 8 bits. 

The normal closing of an TCP connection corresponds to an EOF packet. Closing due to an 
error, such as Host r3cad, corresponds to a CLS packet. 

26.9.11 Host Table 

I'he HOSTAB protocol may be used to access tables cT host addresses on other networks, such 
as Uie Arpanet or Internet Servers for tliis protocol currently exist for Tcncx, l’OPS-20, ITS, 
and Lisp Machines. 

'I’he user connects to contact name HOSTAB, undertakes a number of transactions, then closes 
tlie connection. Each transaction is initiated by tlie user transmitting a host name followed by a 
carriage return. I'he server responds with information about that host terminated with an EOF, 
and is tlten ready for another transaction. 'I’he server’s response consists of a number of attributes 
of the host. F^ch attribute consists of an identifying name, a space character, the value of the 
attribute, and a carriage return. Values may be strings (free of carriage returns and not 
surrounded by double-quotes) or octal numbers. Attribute names and most values are in upper 
case. 'I'here can be more than one attribute with the same name; for example, a host may have 
more than one name or more than one network address. 


PS:<I .MAN>CHAOS.rFXT.25 


8-JUN-84 



631 


I iighcr-l cvcl I’rotwols 


l isp Miichinc Mamuil 


Hie standard attribute names defined now are as follows. Note that more are likely to be 
added in tlie future. 

ERROR The value is an error message. The only error one might expect to get is “no 

such host”. 

NAME The value is a name of tlie host. There may be more tlian one NAME attribute; 

the first one is always tlie official name, and any additional names arc nicknames. 

MACHINE-TYPE 

Tlie value is tlie type of machine, such as LISPM, PDPIO, etc. 


SYSTEM-TYPE 

The value is the type of software running on the machine, such as LISPM, 
etc. 

ITS, 

ARPA 

The value is an address of tlie host on the Arpanet, in tlie form hust/imp. 
two numbci's arc decimal. 

The 

CHAOS 

The value is an address of the host on Chaosnet, as an octal number. 


DIAL 

TTic value is an address of the host on Dialnet, as a telephone number. 


LCS 

ITie value is an address of the host on tlie LCSnct, as two octal numbers 
separated by a slash. 

SU 

The value is an address of the host on the SUnct, in the form net#host. 
two numbers arc octal. 

Die 


26.9.12 Dover 

A press file may be sent to the Dover printer at MIT by connecting to contact name DOVER 
at host AI-CHAOS-11. This host provides a protocol translation service tliat translates from 
Chaosnet stream protocol to the EFTP protocol spoken by the Dover printer. Only one file at a 
time can be sent to the Dover, so an attempt to use this service may be reftiscd by a CLS packet 
containing the string "BUSY". Once the connection has been established, the press file is 
transmitted as a sequence of 8-bit bytes in data packets (opcode 200). It is necessary to provide 
packets rapidly enough to keep the Dover’s program (Spruce) from timing out; a packet every 
five seconds suffices. Of course, packets are normally transmitted much more rapidly. 

Once the file has been transmitted, an EOF packet must be sent. Die transmitter must wait 
for that EOF to be acknowledged, then send a second one, and then close the connection. The 
two EOF’s are necessary to provide the proper connection-closing sequence for tlie EFTP protocol. 
Once the press file has been transmitted to the Dover in this way and stored on the Dover’s local 
disk, it will be processed, prepared for printing, and printed. 

If an error message is returned by the Dover while the press file is being transmitted, it is 
reported back through the Chaosnet as a LOS containing the text of tlie error message. Such 
errors are fairly common; the sender of the press file should be prepared to retry the operation a 
few times. 

Most programs that send press files to the Dover first wait for the Dover to be idle, using the 
Foreign ProttKol mechanism of Chaosnet to check the status of tlie Dover. TTiis is optional, but 
is courteous to other users since it prevents printing from being held up while additional files are 
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sent to the Dover and queued on its local disk. 

It would be possible to send to a press file to the Dover using its EFTP protocol Uirough tlic 
Foreign Protocol niahanism, rallicr Uttin using the AI -CFIAOS-11 gateway service. This is not 
usually done because EFTP, which requires a handshake for every packet, tends to be very slow 
on a timesharing system. 

26.9.13 Remote Disk 

The Remote Disk server exists on l.isp Machines to allow other machines to refer to or 
modify the contents of tlic l.isp Machine’s disk. Primarily Uiis is used for printing and editing tlic 
disk label. 

After first establishing a connection to contact name REMOTE-DISK, the user process sends 
commands as packets which contain a line of text, ending with a Return character. ITie text 
consists of a command name, a space, and arguments intcipreted according to the command. The 
server processing the command may send disk daui to tlic user, or it may read successive packets 
and write them to the disk. It is up to the user to know how many packets of disk data to read 
or send after each command. The commands arc: 

READ unil block n-blocks 

Reads n-blocks of data from disk unit sterting at block and transmits their contents 
to die user process. 

WRITE unit block n-blocks 

Reads data from the net connection and stores it into n-blocks disk blocks on disk 
unit starting at block. 

SAY text Prints text, which is simply all the rest of the line following SAY, on the screen 
of the server host as a notification. 

Each disk bliKk is transmitted as three packets, die first two containing the data for 121 
(decimal) Lisp Machine words, and the third containing the data for die remaining 14 (decimal) 
words of the disk block. Each packet’s data ends with a checksum made by adding together all 
the 8-bit bytes of die actual disk data stored in the packet. 


26.9.14 The Eval Server 

The Eval server Is available on Lisp Machines with contact name EVAL. It provides a read* 
eval-print loop which reads and prints using die Chaosnet connection. The data consists of text in 
die ASCII character set 

Each time a complete s-expression arrives, the Eval server reads it, evaluates it and prints the 
list of values back onto the network connection, followed by a CRLF. 'Ihere is no way for the 
user prwess to tell the end of the output for a particular s-expression; the usual application is 
simply to copy all the output to a user's terminal asynchronously. y 
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I'hc Hval server is disjiblcd when the Lisp Machine is logged in, unless die user requests to 
enable it. 

chaos:eval-serv0P-on mode 

Turn the l-.val server on this l.isp Machine on or off. mode can be t (on), nil (off), or 
:notify (on, but notify the user when a connection is made). 

26.10 Using Higher Level Protocols 

qsend user &optional text 

Sends a message to another user, qsend is different from mail because it sends the 
mcssjigc immediately; it will appear within seconds on die other user's screen, rather than 
being saved in her mail file. 

user should be a string of the form ” usernameQhoslname"\ host is the name of the lasp 
Machine or timesharing system the user is currently logged-in to. Multiple recipients 
separated by commas arc also allowed, text is a string which is the message. If text is 
not specified, you arc prompted to type in a message. 

Unlike mail and bug. qsend docs not put up a window to allow you to compose the 
message; it just reads it from the input stream. Use Converse if you wish to compose 
sends in the editor. Converse can be invoked by typing System C. If you have started 
typing in a message to qsend, you can switch to Converse by typing Control-Meta-E 
(“Edit”). Tlic text you have typed so far is transferred into Converse. 

qsend docs give you the ability to insert the text of the last message you received. Type 
Control-Meta-Y to do this. 

reply &optional text 
qreply &opUonal text 

Sends text as a message to the last user who sent a message to you, like qsend with an 
appropriate first argument provided. The two names are synonymous. 

chaos:shout &optional message 

Sends message to every Lisp Machine at your site. If you do not specify message, it is 
read from ‘standard-input*. 

pr1nt-sends 

Reprints any messages that have been received. This is useful if you want to see a 
message again. 

supdup &optional host 

host may be a string or symbol, which is taken as a host name, or a number, which is 
taken as a host number. If no host is given, the machine you are logged-in to is 
assumed. Ihis function opens a connection to the host over the Chaosnet using the 
Supdup protocol, and allows the Lisp Machine to be used as a terminal for any ITS, 
UNIX or TOPS-20 system. 
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To give commands to supdup, type the Netw/ork key followed by one character. I’ypc 
Network followed by Help for documentation. 

telnet &optional host simulate-imiac 

telnet is similar to supdup but uses die Arpanet-standard Telnet proUKol, simulating a 
printing terminal rather than a display terminal. 

hostat &rest hosts 

Asks each of the hosts for its status using the STATUS protocol, and prints the results. If 
no hosts are specified, all hosts on Uic Chaosnet arc asked. Hosts can be specified citlicr 
by name or by number. 

For each host, a line is output that either says that tlie host is not responding or gives 
metering infonnation for die host’s network attachments. If a host is not responding, that 
usually means that it is down or there is no such host at diat address. A I.isp Machine 
can fail to respond if it is looping inside without-interrupts or paging extremely heavily, 
such that it is simply unable to respond within a reasonable amount of dme. 

finger &optional spec (i/rcom *standard"Output*) 
whols &optional s/?cc ‘standard-output*) 

Prints brief (finger) or verbose (whois) information about a user or users specified by 
spec, on stream, spec can be a user name, @ followed by a host name, or a user name, 
@, and a host name. If there is no host name, the default login host is used. If there 
is no user name, all users on the host arc described. 

Examples: 

(finger "@0Z") 

(whois "RMS@0Z") 

chaostflnger-all-Ims &optional stream print-free return-free hosts 

Prints a line of information about the user of each Lisp Machine in hosts (the default is 
all Lisp Machines at this site) on stream (default is ’standard-output*). 

If print-free is non-nil, information on free Lisp Machines and nonresponding Lisp 
Machines is also printed. 

If return-free is non-nil, then this ftmetion returns two values, the first a list of host 
objects of free Lisp Machines, die second a list of host objects of nonresponding Lisp 
Machines. 

chaos:user-logged-1nto-host-p username host 

Returns t if there is a user named username logged in on host (a host name or host 
object). 

chaos:f 1 nd-hosts-or- 11 spms-logg 0 d- 1 n-as-us(jr user hosts 

Return a list of host objects for hosts on which user is logged in. All Lisp Machines at 
this site arc checked, and so arc hosts (which arc presumably non-Lisp machines). 


PS:<L.MAN>CHAOS.rF:XT.25 


8-JUN-84 



1 isp Miichinc Mamial 


635 


Lising I lighcr 1 cvcl Protocols 


tv:close-all-servers mivoH 

Close the connections of all network servers on this Lisp Machine, giving reason (a string) 
as the reason in the CLS packet. 

Note that PL1-;K has a mode tliat displays infonnalion on die active network servers. 
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27. Packages 

A Lisp program is a collection of function definitions. I'hc functions arc known by tlicir 
names, and so each must have its own name to identify it. Clearly a programmer must not use 
the same name for two diflcrcnt functions. 

The Lisp Machine consists of a huge Lisp environment, in which many programs must 
coexist. All of the operating system, the compiler, the cdiU)r, and a wide variety of programs are 
provided in tlic initial environment. Furilicrmorc, every program that you use during a session 
must be loaded into the same environment, liijch of these programs is composed of a group of 
functions; apparently each function must have its ova'll distinct name to avoid conflicts. For 
example, if tlic compiler had a function named pull, and you loaded a program which had its 
own function named pull, the compiler's pull would be redefined, probably breaking the compiler. 

It would not really be possible to prevent Uiesc conflicts, since the programs arc written by 
many different people who could never get together to hash out who gets the privilege of using a 
specific name such as pull. 

Now, if we are to enable two programs to coexist in the Lisp world, each with its own 
function pull, then each program must have its own symbol named pull, because tlicre can’t be 
two function definitions on tlic same symbol. This mcjans tliat separate name spaces—mappings 
between names and symbols—must be provided for the two programs. The package system is 
designed to do just that. 

Under the package system, the author of a prograjn or a group of closely related programs 
identifies them together as a package. The package system associates a distinct name space with 
each package. 

Here is an example: suppose there arc two programs named chaos and arpa, for handling 
the Chaosnet and Arpanet respectively. 'Fhe author of each program wants to have a function 
called get-packet, which reads in a packet from the network (or something). Also, each wants 
to have a function called allocate-pbuf, which allocates the packet buffer. Each “get” routine 
first allocates a packet buffer, and then reads bits into die buffer; therefore, each version of get- 
packet should call the respective version of allocate-pbuf. 

Without the package system, the two programs could not coexist in the same Lisp 
environment. Hut die package feature can be used to provide a separate name space for each 
program. What is required is to define a package named chaos to contain the Chaosnet program, 
and another package arpa to hold the Arpanet program. When the Chaosnet program is read 
into the machine, its symbols would be entered in the chaos package’s name space. So when the 
Chaosnet program's get-packet referred to allocate-pbuf, the allocate-pbuf in the chaos name 
space would be found, which would be the allocate-pbuf of the Chaosnet program—the right 
one. Similarly, tlie Arpanet program’s get-packet would be read in using the arpa package and 
would refer to the Arpanet program’s allocate-pbuf. 

In order to have multiple name spaces, tlic function intern, which searches for a name, must 
allow the name space to be specified, intern accepts an optional second argument which is the 
package to search. 
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It's obvitnis dial every file lias to be loaded into the right package to serve its puiposc. It 
may not be so obvious that every file must be compiled in die right package, but it s just as true, 
l.uckily, this usually happens automatically. 

The system can get die package of a source file from its line, for instance, you can put 

at die front of your file a line such as 

; Mode:Lisp: PackagetSystein-Internals 

The compiler puts the package name into die QFASl. file for use when it is loaded. If a file 
doesn’t have such a package specification in it, the system loads it into die current package and 

tells you w-hat it did. 


27.1 The Current Package 


At any time, one package is die current package. By default, symbol lookup happens in the 
current package. 


Variable 

•package* . . . 

The value of the this variable is the current package, intern searches this package if it is 

not given a second argument. Many other functions for operating on packages also use 
this as the default. ^ 


Setting or binding the variable changes the current package. May die Goddess help you if 
you set it to something dial isn’t a package! 


The two names are synonymous. 


Each process or stack group can have its own setting for the current package by binding 
♦package* with let. The actual current package at any time is the value bound by the process 
which is running, 'fhe bindings of another process are irrelevant until the process runs. 


pkg-bind pkg body... r u l i a 

pkg may be a package or a package name. The forms of the body are evaluated 

sequentially with the variable ‘package* bound to the package named by pkg. 

Example: 

(pkg-bind "ZV/EI" 

(read-from-string function-name)) 


When a file is loaded, ‘package* is bound,to the correct package for the file (the one 
named in the file’s -•- line). The Chaosnet program file has Package: Chaos; in the -•- line, 
and therefore its symbols are looked up in the chaos package. A QFASL file has an encoded 
representation of the -*- line of the source file; it looks different, but it serves the same 

purpose. 

The current package is also relevant when you type Lisp expressions on the keyboard, it 
controls the reading of the symbols that you type. Initially it is the package user. You can select 
a different package using pkg-goto, or even by setqing ‘package*. If you arc working with the 
Chaosnet program, it might be useful to type (pkg-goto ’chaos) so that your symbols arc found 
in the chaos package by default. The Lisp listen loop binds ‘package* so that pkg-goto m 
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one l.isp listener docs not allcct others, or any other processes whatever, 
plcg^goto package &opiional globally 

Sets ^package* to package, if package is suitable. (Autoexporting packages used by 
other packages arc not suitable because it you could cause great troubles by interning new 
symbols in them), package may be specified as a package object or tlic name of one. If 
globally is non-nil, then this function also calls pkg-goto-globally (see below) 

The Zmacs editor records the correct package for each buffer; it is determined from the file’s 
line. This package is used whenever expressions an; read from tlic buffer. So if you edit tlic 
definition of the Chaosnet get-packet and recompile it, die new definition is read in die chaos 
package. The current butrer's package is also used for all expressions or symbols typed by die 
user. Thus, if you type Meta-, allocate-pbuf while looking at die Chaosnet program, you get 
die definition of the allocate-pbuf function in die chaos package. 

'I’lie variable ‘package* also has a global binding, which is in effect in any process or stack 
group which docs not rebind die variable. New prtKCsscs diat do bind ‘package* generally use 
the global binding to initialize their own bindings, doing (let ((‘package* ‘package*)) ...). 
'riicrcforc, it can be useful to set die global binding. But you cannot do diis with setq or pkg- 
goto from a l.isp listener, or in a file, because that will set the local binding of ‘package* 
instead. Therefore you must use setq-globally (page 35) or pkg-goto-globally, 

pkg-goto-globally package 

Sets die global binding of ‘package* to package. An error is signaled if package is not 
suitable. Bindings of package other than the the global one are not changed, including 
die current binding if it is not die global one. 

ITic name of the current package is always displayed in the middle of the who line, with a 
colon following it. lliis describes die process which the who line in general is describing; 
normally, die process of the selected window. No matter how the current package is changed, 
die who line will eventually show it (at one-second internals). Thus, while a file is being loaded, 
die who line displays that file’s package; in the editor, the who line displays the package of the 
selected buffer. 

27.2 Package Prefixes 

The separation of name spaces is not an uncrossablc gulf. Consider a program for accessing 
files, using the Chaosnet. It may be useful to put it in a disdnet package file-access, not 
chaos, so tiiat the programs are protected from accidental name conflicts. But the file program 
cannot exist without referring to the functions of die Chaosnet program. 

The colon character (’:’) has a special meaning to tfie Lisp reader. When die reader sees a 
colon preceded by the name of a package, it reads the next Lisp object with ‘package* bound 
to dial package. Thus, to refer to the symbol connect in package chaos, we write 
chaosiconnect. Some symbols dcKumcntcd in diis manual require package prefixes to refer to 
them; dicy arc always written with an appropriate prefix. 
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Similarly, if tlic chaos program wanted to refer to the arpa program’s allocate-pbuf 
function (for some reason), it could use arpa:allocate-pbuf. 

Package prefixes are printed on output also. If you would need a package prefix to refer to a 
symbol on input, then the symbol is printed with a suitable package prefix if it supposed to be 
printed readably (print, as opposed to princ). Just as the current package affects how a symbol 
is read, it also affects how the symbol is printed. A symbol available in the current package is 
never printed with a package prefix. 

I'hc printing of package prefixes makes it possible to print list structure containing symbols 
from many packages and read the text to produce an equal list with the same symbols in 
it—provided the current package when the text is read is the s;tmc one that was current when the 
text was printed. 

The package name in a package prefix is read just like a symbol name. This means that 
escape characters can be used to include special characters in the package name. I'hus, 
foo/:bar:test refers to the symbol test in the package whose name is “FOOtBAR", and so docs 
|FOO:BAR|:test. Also, letters are converted to upper ease unless they arc escaped. F'or tliis 
reason, the actual name of a package is normally all upper ease, but you can use either case 
when you write a package prefix. 

In Common Lisp programs, simple colon prefixes are supposed to be used only for referring 
to external symbols (see page 642). 'fo-refer to other symbols, one is supposed to use two colons, 
as in chaos::lose-it-later. 'fhe Lisp machine tradition is to allow reference to any symbol with a 
single colon. Since tJiis is upward compatible with what is allowed in Common Lisp, single-colon 
references arc always allowed. However, double-colon prefixes are printed for internal symbols 
when Common Lisp syntax is in use, so that data printed on a Lisp Machine can be read by 
other Common Lisp implementations, 

27.3 Horae Packages of Symbols 

Each symbol remembers one package which it belongs to; normally, the first one it was ever 
interned in. This package is available as (symbol-package symbol). 

With make-symbol (see page 133) it is possible to create a symbol that has never been 
interned in any package. It is called an uninterned symbol, and it remains one as long as nobody 
interns it. 'fhe package cell of an uninterned symbol contains nil. Uninterned symbols print with 
#: as a prefix, as in #:foo. This syntax can be used as input to create an uninterned symbol 
with a specific name; but a new symbol is created each time you type it, since tlic mechanism 
which normally makes symbols unique is interning in a package. Thus, (eq #:foo #:foo) 
returns nil. 

symbol-package symbol 

Returns the contents of symbol's package cell, which is the package which owns symbol, 
or nil if symbol is uninterned. 
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package-cell-locatlon xymbol 

Returns a loeativc pointer to .yvn/w/’s package cell. It is preferable to write 
(locf (symbol-package symbol)) 
rather titan calling this function explicitly. 

Printing of package prefixes is based on the contents of the symbol’s package cell. If tltc cell 
contains the chaos package, then chaos: is printed as the prefix when a prefix is necessary. As a 
result of obscure actions involving interning and uninterning in multiple packages, the symbol may 
not actually be present in chaos any more. Then the printed prefix is inaccurate, 'lliis cannot be 
helped. If the symbol is not where it claims to be, there is no easy way to find wherever it 
might be. 

27.4 Keywords 

Distinct name spaces arc useful for symbols which have function definitions or values, to 
enable tJicm to be used independently by different programs. 

Another way to use a symbol is to check for it with eq. Then there is no possibility of name 
conflict. For example, the function open, part of tlie file system, checks for tlie symbol terror in 
its input using eq. A user function might do tlie same thing. Then the symbol terror is 
meaningful in two contexts, but these meanings do not affect each other. 'Fhe fact that a user 
program contains the code (eq sym terror) does not interfere with the function of system code 
which contains a similar expression. 

There is no need to separate name spaces for .symbols used in this way. In fact, it would be 
a disadvantage. If both the Chaosnet program and tlie Arpanet program wish to recognize a 
keyword named “address”, for similar purposes (naturally), it is very uscftil for programs that can 
call cither one if it is the same keyword for either program. But which should it be? 
chaostaddress? arpataddress? 

To avoid this uncertainty, one package called keyword has been set aside for the keywords of 
all programs. The Chaosnet and Arpanet programs would both look for keywordtaddress, 
normally written as just taddress. 

Symbols in keyword are the normal choice for ntimes of keyword arguments; if you use 
&key to process them, code is automatically generated to look for for symbols in keyword. They 
are also the normal choice for flavor operation nam<JS, and for any set of named options 
meaningful in a specific context. 

keyword and the symbols belonging to it are treated differently from other packages in a 
couple of ways designed to make tliem more convenient for this usage. 

* Symbols belonging to keyword are constants; they always evaluate to themselves. (This is 
brought about by storing the symbol in its own value cell when the symbol is placed in the 
package). So you can write Just terror rather than ’terror. The nature of tlie application of 
keywords is such that they would always be quoted if they were not constant. 

* A colon by itself is a sufficient package prefix for keyword. This is because keywords are the 
most frequent application of package prefixes. 
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t if object is a symbol which belongs to die keyword package. 

There are certain cases when a keyword should not be used for a symbol to be cheeked for 
with eq. Usually this is when the symbol 1) does not need to be known outside of a single 
program, and 2) is to be placed in shared data bases such as property lists of symbols which may 
sometimes be in global or keyword. Kor example, if the Chaosnet program were to record the 
existence of a host named CAR by placing an :address property on the symbol :car, or the 
symbol car (notice that chaos:car is car), it would risk conflicts with other programs that might 
wish to use die taddress property of symbols in general. It is better to call the property 
chaos:address. 

27.5 Inherilancc between Name Spaces 

In die simplest (but not die default) case, a package is independent of all other packages. 
'This is not the default because it is not usually useful. Consider the standard Lisp function and 
variables names, such as car: how can the Chaosnet program, using the chaos package, access 
them? One way would be to install all of diem in die chaos package, and every other package. 
But it is better to have one table of die standard Lisp symbols and refer to it where necessary. 
'This is called inheritance. The single package global is the only one which actually contains the 
standard Lisp symbols: other packages such as chaos contain directions to “search global too”. 

Each package has a hash table of the symbols, 'flic symbols in this table are said to be 
present (more explicitly, present directly) in the package, or interned in it. In addition, each 
package has a list of other packages to inherit from. By default, this list contains the package 
global and no others; but packages can be added and removed at any time with the functions 
use-package and unuse-package. We say that a package uses the packages it inherits from. 
Both the symbols present directly in the package and the symbols it inherits are said to be 
available in the package. 

Here’s how this works in the above example. When the Chaosnet program is read into the 
Lisp world, the current package would be the chaos package. Thus all of the symbols in the 
Chaosnet program would be interned in the chaos package. If there is a reference to a standard 
Lisp symbol such as append, nothing is found in the chaos package’s own table; no symbol of 
that name is present directly in chaos. 'Therefore the packages used by chaos are searched, 
including global. Since global contains a symbol named append, tliat symbol is found. If, 
however, there is a reference to a symbol that is not standard, such as get-packet, the first time 
it is used it is not found in either chaos or global. So intern makes a new symbol named get- 
packet and installs it in the chaos package. When get-packet is referred to later in the 
Chaosnet program, intern finds get-packet immediately in the chaos package, global does not 
need to be searched. 

When the Arpanet program is read in, the current package is arpa instead of chaos. When 
the Arpanet program refers to append, it gets the global one: that is, it Shares the same one 
tliat die Chaosnet program got. However, if it refers to get-packet, it docs not get die same 
one the Chaosnet program got, because die chaos package is presumably not used by arpa. 'The 
get-packet in chaos not being available, no symbol is found, so a new one is created and 
placed in the arpa package. Further references in the Arpanet program find that get-packet. 
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This is the desired result; die packages share the standard l isp symbols only. 

Inheritance between other packages can also be useful, but it must be restricted: inheriting 
only some of the symbols of the used package. If the lile access program refers frequently to the 
advertised symbols of the Chaosnet program—the connec tion states, such as open-state, functions 
such as connect, listen and open-stream, and othcis—it might be convenient to be able to 
refer to tliese symbols from the file-access package without need for package prefixes. 

One way to do this is to place the appropriate symbols of the chaos package into the file- 
access package as well, i'hen they can be accessed hj' the file access program just like its own 
symbols. Such sharing of symbols bctw'cen packages inner happens from tlie ordinary operation 
of packages, but it can be requested explicitly using import. 

Import symbols &optional (package *package*) 

Is the standard Common Lisp way to insert a specific symbol or symbols into a package. 
symbols is a symbol or a list of symbols. Kach of the specified symbols becomes present 
directly in package. 

If a symbol with the same name is already present (directly or by inheritance) in package. 
an error is signaled. On proceeding, you can say whether to leave the old symbol there 
or replace it with the one specified in import. 

Hut importing may not be the best solution. .All callers of tlic Chaosnet program probably 
want to refer to the same .set of symbols: tlte symbols described in the documentation of the 
Chaosnet program. It is simplest if tlie Chaosnet progi'am, rather tlian each caller, says which 
symbols they are. 

Restricted inheritance allows the chaos package to specify which of its symbols should be 
inheritable. 'Lhcn file-access can use package chaos ami the desired symbols are available in it. 

The inheritable symbols of a package such as chaos in this example arc called external; the 
other symbols arc internal. Symbols arc internal by default. Ihc function export is how symbols 
are made external. Only the external symbols of a package arc inherited by other packages which 
use it. This is true of global as well; Only external symbols in global arc inherited. Since 
global exists only for inheritance, every symbol in it is external; in fact, any symbol placed in 
global is automatically made external, global is said to be autoexporting. A few other packages 
with special uses, such as keyword and fonts, arc autoexporting. Ordinary packages such as 
chaos, which programs are loaded in, should not be. 

If a request is made to find a name in a package, first the symbols present directly in that 
package arc searched. If the name is not found that way, tlicn all the packages in the used-list 
are searched; but only external symbols are accepted. Internal symbols found in the used 
packages are ignored. If a new symbol needs to be created and put into tlie name space, it is 
placed directly in the specified package. New symbols are never put into tlie inherited packages. 

The used packages of a package arc not in any particular order. It docs not make any 
difference which one is searched first, because they are not allowed to have any conflicts among 
them. If you attempt to set up an inheritance situation where a conflict would exist, you get an 
error immediately. You can tlicn specify explicitly how i.o resolve the conflict. See section 27.7, 
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page 647. 

I'hc packages used by the packages used arc not searched. If package file-access uses 
package chaos and file mypackage uses package file-access, tliis docs not cause mypackage to 
inherit anything from chaos. I'his is desirable; the Chaosnet functions for whose sake file- 
access uses chaos arc , not needed in die programs in mypackage simply to enable them to 
communicate with file-access. If it is desirable for mypackage to inherit from chaos, tliat can 
be requested explicitly. 

These functions arc used to set up and control package inheritance. 

use-package packages &optional (//I'/wArtge‘package*) 

Makes in-package inherit symbols from packages, which should be either a single package 
or name for a package, or a list of packages and/or names for packages. 

'This can cause a name conflict, if any of packages has a symbol whose name matches a 
symbol in in-package. In this ease, an error is signaled, and you must resolve the conflict 
or abort. 

unuse-package packages &optional (//j-pacAroge ‘package*) 

Makes in-package cease to inherit symbols from packages. 

package-use-11st package 

Returns the list of packages used by package. 

package-used-by-list package 

Returns the list of packages which use package. 

You can add or remove inheritance paths at any time, no matter what else you have done 
with the package. 

These functions are used to make symbols external or internal in a package. By default, they 
operate on the current package. 

export symbols &optional (jmekage*package*) 

Makes symbols external in package, symbols should be a symbol or string or a list of 
symbols and/or strings, fhe specified symbols or strings are interned in package, and the 
symbols found are marked external in package. 

If one of the specified symbols is found by inheritance from a used package, it is made 
directly present in package and then marked external there. (We know it was already 
external in the package it was inherited from.) 

Note that if a symbol is present directly in several packages, it can be marked external or 
internal in each package independently. Thus, it is tlte symbol’s presence in a particular 
package which is external or not, rather than the symbol itself, export makes symbols 
external in whichever package you specify; if the same symbols are present directly in any 
other package, their status as external or internal in the other package is not affected. 
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unexport symbols &opti()nal (/x/cArfge’package*) 

Makes symbols not be external in package. An error occurs if any of the symbols fails to 
be directly present in package. 

package-external-symbols package 

Returns a list of all tlie external symbols of package. 

globalize name-or-symbol &optuma\ (inlo-package "GLOBAL”) 

Sometimes it will be discovered tliat a symbol which ought to be in global is not there, and 
tlic file defining it has already been loaded, thus mistakenly creating a symbol with that name in 
some other package. Creating a symbol in global would not fix the problem, since pointers to 
tlie misbegotten symbol already exist. Kven worse, similarly named symbols may have been 
created mistakenly in other packages by code attempting to refer to tlie global symbol, and those 
symbols also are already pointed to. globalize is designed for use in correcting such a situation. 

globalize symbnl-orslring &optional (package "GLOBAL") 

If name-or-symbol is a name (a string), interns the name in inlo-package and then 
forwards together all symbols with the same name in all the packages Uiat use inlo- 
package as well as in inlo-package itself. I'hcse symbols arc forwarded together so that 
they become effectively one symbol as far as die value, flinction definition and properties 
are concerned. The value of the composite is taken from whichever of the symbols had a 
value; a prcKccdable error is signaled if multiple, distinct values were found. The 
function definition is treated similarly, and so is each property that any of the symbols 
has. 

If name-or-symbol is a symbol, globalize interns that symbol in inlo-package and then 
forwards the other symbols to that one. 

The symbol which ultimately is present in inlo-package is also exported. 

27.6 Packages and Interning 

ITic most important service of the package system is to look up a name in a package and 
return the symbol which has that name in the package’s name space. This is done by the 
function intern, and is called inierning. When you type a symbol as input, read converts your 
characters to the actual symbol by calling intern. 

Tlie function intern allows you to specify a package as the second argument. It can be 

specified by giving either the package object itself or a string or symbol that is a name for the 

package, intern returns three values. The first is tlie interned symbol, 'flie second is a keyword 

that says how the symbol was found, 'llic third is the package in which the symbol was actually 

found. 'I'liis can be either the specified package or one of its used packages. 

When you don’t specify the second argument to inbjrn, the current package, which is the 
value of the symbol ’package*, is used. This happens, in particular, when you call read and 
read calls intern. To specify the package for such functions to use, bind the symbol ’package* 
temporarily to the desired package with pkg-bind. 
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I'hcrc arc actually four forms of the intern function; regular intern, intern-soft, intern- 
local. and intern-local-soft, -soft means that the symbol should not be added to the package if 
there isn’t already one; in that case, all three values arc nil. -local turns off inheriutnee, it 
means Uiat die used packages should not be searched. Ihus, intern-local can be used to cause 
shadowing, intern-local-soft is right when you want complete control over what packages to 
search and wltcn to add symbols. All four forms of intern return the same tlircc values, except 
tliat tlic soft forms return nil nil nil when die symbol isn't found. 

Intern strhig-oi^symbol &optional (/)Ag *package*) 

'I’he simplest case of intern is where sirins-or-symbal is a string. (It makes a big 
difference which one you use.) intern searches pk^ and its used packages sequentially, 
looking for a symbol whose print-name is equal to siring-oi-symbol. If one is found, it is 
returned. Otherwise, a new symbol with slring-oi^symbol as print name is created, placed 
in package pkg, and returned. 

The first value of intern is always die symbol found or created. I’hc second value tells 
whether an existing symbol was found, and how. It is one of these four values; 

:internal A symbol was found present directly in pkg, and it was internal in pkg. 

;external A symbol was found present directly in pkg, and it was external in pkg. 

rinherited A symbol was found by inheritance from a package used by pkg. You 
can deduce that, the symbol is external in dial package. 

nil A new symbol was created 

The third value returned by intern says which package the symbol found or created is 
present directly in. This is different from pkg if and only if if the second value is 
:inherited. 

If string-oi^symbol is a symbol, the search goes on just the same, using the print-name of 
siring-oi^symbol as the string to search for. But if no existing symbol is found, siring-or 
symbol itself is placed directly into pkg, just as import would do. No new symbol is 
created; string-or-symbol itself is the “new” symbol. 'I’his is done even if string-or-symbol 
is already present in another package. You can create arbitrary arrangements of sharing of 
symbols between packages this way. 

Note; intern is sensitive to case; that is, it will consider two character strings different 
even if the only difference is one of upper-case versus lower-case. The reason that 
symbols get converted to upper-case when you type them in is that the reader converts 
the case of characters in symbols; the characters are converted to upper-case before intern 
is ever called. So if you call intern with a lower-case "too" and dien with an upper-case 
"FOO", you won’t get the same symbol. 

Intern-local string-or^symbol Aopdonal (pAg * package*) 

Like intern but ignores inheritance. If a symbol whose name matches string-or-symbol is 
present directly in pkg, it is returned; otherwise string-or-symbol (if it is a symbol) or a 
new symbol (if string-or-symbol is a string) is placed directly in pkg. 
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intern-local returns second and third values v/ith the same meaning as those of intern. 
However, the second value can never be :inherited, and the third value is always pkg. 

I'hc function import is implemented by passing the symbol to be imported to intern- 
local. 

Intern-soft suing &optional (/jAg*package*) 
find-symbol string &optional (pAg‘package*) 

Like intern but never creates a symbol or modifies pkg. If no existing symbol is found, 
nil is returned for all tliree values. It makes no important difference if you pass a symbol 
instead of a siring. 

intern-soft returns’second and third values with the same meaning as those of intern. 
However, if the second value is nil, it does not mean that a symbol was created, only 
tliat none was found. In this case, tlie Uiird value is nil raUicr than a package. 

find-symbol is the Common Lisp name for this function. The two names arc 
synonymous. 

Intern-local-soft string «&optional (pAg‘package*) 

Like intern-soft but without inheritance. If a matching symbol is found directly present 
in pkg, it is returned; otherwise, die value is nil. 

intern-local-soft returns second and third values with the same meaning as those of 
intern. However, if the second value is nil, it docs not mean dial a symbol was created, 
only that none was found. Also, it can never be inherited. Ihe third value is rather 
useless as it is either pkg, or nil if the second value is nil. 

remob symbol &optional (pncAugr(symbol-package s>w6o/)) 
unIntern symbol &optional (pncAage‘package*) 

Both remove symbol from package, symbol itself is unaffected, but intern will no longer 
find it in package, symbol is not removed from any other package, even packages used 
by package, if it should be present in them. If symbol was present in package (and 
therefore, was removed) then the value is t; otherwise, the value is nil. 

In remob, package defaults to die contents of the symbol’s package cell, the package it 
belongs to. In unintern, package defaults to die current package, unintern is the 
Common Lisp version and remob is die traditional version. 

If package is the package \hat symbol belongs to, then symbol is marked as unintemed: 
nil is stored in its package cell. 

If a shadowing symbol is removed, a previously-hidden name conflict between distinct 
symbols with the same name in two used packages can suddenly be exposed, like a 
discovered check in chess. If this happens, an error is signaled. 
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27.7 Sliadowiiig and Name Conflicts 

In a package that uses global, it may be desirable to avoid inheriting a few standard l.lsp 

symbols. Perhaps the user has defined a function copy-list, knowing tliat this symbol was not in 

global, and tlten a system function copy-list was created:as part of supporting Common l.isp. 
Radter than changing the name in his program, he can shadow copy-list in the programs 
package. Shadowing a symbol in a package means putting a symbol in that package which hides 
any symbols with the same name which could otherwise have been inherited there. Ihc symbol is 
explicitly marked as a shadowing symbol so that the name conflict docs not result in an error. 

Shadowing of symbols and shadowing of bindings arc quite distinct. The same word is used 

for them because they arc both examples of tlic general abstract concept of shadowing, which is 

meaningful whenever there is inheritance. 

Shadowing can be done in tlic definition of a package (see page 652) or by calling the 
function shadow, (shadow "COPY-LIST") creates a new symbol named copy-list in die current 
package, regardless of any symbols with that name already available diroiigh inhcriUincc. Once 
the new symbol is present directly in the package and marked as a shadowing symbol, the 
potentially inherited symbols are irrelevant. 

shadow names &opiional (poc^Age * package*) 

Makes sure that shadowing symbols with the specified names exist in package, names is 
cither a string or symbol or a list of such. If symbols arc used, only their names matter; 
they arc equivalent to strings. Each name specified is handled independently as follows: 

If there is a symbol of that name present directly in package, it is marked as a 
shadowing symbol, to avoid any complaints about name conflicts. 

Otherwise, a new symbol of that name is created and interned in package, and marked as 
a shadowing symbol. 

Shadowing must be done before programs are loaded into the package, since if the programs 
are loaded without shadowing first they will contain pointers to the undesired inherited symbol. 
Merely shadowing the symbol at this point does not alter those pointers; only reloading the 
program and rebuilding its data structures from scratch can do that. 

If it is necessary to refer to a shadowed symbol, it can be done using a package prefix, as in 
global:copy-list. 

Shadowing is not only for symbols inherited from global; it can be used to reject inheritance 
of any symbol. Shadowing is the primary means of resolving name conflicts in which there 
multiple symbols with the same name are available, due to inheritance, in one package. 

Name conflicts are not permitted to exist unless a resolution for the conflict has been stated in 
advance by specifying explicitly which symbol is actually to be seen in package. If no resolution 
has been specified, any command which would create a name conflict signals an error instead. 

For example, a name conflict can be created by use-package if it adds a new used package 
with its own symbol foo to a package which already has or inherits a different symbol with the 
same name foo. export can cause a name conflict if tlie symbol becoming external is now 
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supposed to be inherited by another package which already has a conflicting symbol. On either 
occasion, if shadowing has not already been pcrfonBcd to control tlic outcome, an error is 
signaled and the useage or exporUition does not (Kcur. 

The conflict is resolved—in advance, always—by placing the preferred choice of symbol in the 
package directly, and marking it as a shadowing symbol. 'Ihis can be done with the function 
shadowing-import. (Actually, you can proceed from the error and specify a resolution, but this 
works by shadowing and retrying. From die point of vi(;w of die retried t)pcration, die resolution 
has been done in advance.) 

shadowing-Import symbols &optional ipackage * package*) 

Interns the specified symbols in package and marks diem as shadowing symbols, symbols 
must be a list of symbols or a single symbol; strings arc not allowed. 

Hacli symbol specified is placed directly into package, after first removing any symbol 
with the same name already interned in package. 'ITiis is rather drastic, so it is best to 
use .shadowing-import right after creating a package, when it is still empty. 

shadowing-import is primarily useful for choosing one of several conflicting external 
symbols present in packages to be used. 

Once a package has a shadowing symbol named too in it, any other potentially conflicting 
external symbols with name too can come and go-in the inherited packages with no effect. It is 
dicreforc possible to perfonn the use-package of another package containing another foo, or to 
export the foo in one of the used packages, without getting an error. 

In fact, shadow also marks the symbol it creates as a shadowing symbol. If it did not do so, 
it would be creating a name conflict and would always gel. an error. 

package-shadowing-symbols package 

Returns die list of shadowing symbols of package. Each of these is a symbol present 
directly in package. When a symbol is present directly in more than one package, it can 
be a shadowing symbol in one and not in another. 

27.8 Styles of Using Packages 

I'he unsophisticated user need never be aware of die existence of packages when writing his 
programs. His files are loaded into package user by default, and keyboard input is also read in 
user by default. Since all the functions that unsophisticated users are likely to need arc provided 
in die global package, which user inherits from, they are all available without special effort. In 
this manual, functions that arc not in die global package are documented with colons in their 
names, and they arc all external, so typing the name the way it is documented docs work in both 
traditional and Common Lisp syntax. 

However, if you arc writing a generally useful tool, jou should put it in some package other 
than user, so that its internal functions will not conflict with names other users use. If your 
program contains more than a few files, it probably should have its own package just on the 
chance that someone else will use it someday along with other, programs. 
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If your program is large, you can use mulliplc packages to help keep its modules 
independent. Use one package for each module, and export from it those of the module’s 

symbols which arc reasonable for other modules to refer to. lutch package can use the packages 

of other modules that it refers to frequently. 

27.9 Package Naming 

A package has one name, also called die primary name for extra clarity, and can have in 

addition any number of nicknames. All of these names arc defined globally, and all must be 

unique. An attempt to define a package with a name or nickname that is already in use is an 
error. 

Hither die name of a package or one of its nicknames counts as a name for die package. All 
of die functions described below diat accept a package as an argument also accept a name for a 
package (either as a string, or as a symbol vdiosc print-name is die name). Arguments that are 
lists of packages may also contain names among the elements. 

When the package object is printed, its primary name is used. The name is also used by 
default when printing package prefixes of symbols. However, when you create die package you 
can specify that one of the nicknames should be used instead for this purpose, 'fhe name to be 
used for this is called the prefix name. 

Case is significant in package name lookup. Usually package names should be all upper case, 
read converts package prefixes to upper case except for quoted characters, just as it does to 
symbol names, so die package prefix will match the package name no matter what case you type 
it in, as long as the actual name is upper ease; TV:FC)0 and tv:foo refer to the same symbol. 
|tv|:foo is different from diem, and normally erroneous sinee there is no package initially whose 
name is ‘tv’ in lower case. 

In the functions find-package and pkg-find-package, and others which accept package 
names in place of packages, if you specify the name as a string you must give it in the correct 
case: 

(find-package "TV") => the tv package 
(find-package "tv") => nil 

You can alternatively specify the name as a symbol; then the symbol’s pnamc is used. Since 
read converts the symbol’s name to upper case, you can type the symbol in cither upper or lower 
case: 

(find-package ’TV) => the tv package 
(find-package ’tv) => the tv package 
since both use the symbol whose pname is "TV". 

Relevant functions: 

package-name package 

Returns the name of package (as a string). 


PS:<L.MAN>PACKD.TKXT.106 


8-JUN-84 



I’iickiige Naming 650 I isp Machine Manual 


package-nicknames package 

Kciiirns ihc list of nicknames (strings) of package. I'his does not include the name itself. 

package-prefix-print-name package 

Returns llie name to be used for printing package prefixes tliat refer to package. 

rename-package package new^name &optional ue\i>-nicknames 

Makes nc\\.>-uame be the name for package, and makes new-nicknames {i\ list of strings, 
possibly nil) be its nicknames. An error is signaled if the new name or any of tire new 
nicknames is already in use for some other package. 

find-package &optional nse-local-names-package 

Returns the package which name is a name far, or nil if there is none. If use-local- 
names-package is non-nil, the local nicknames ol’ tliat package are checked first. Otherwise 
only actual names and nicknames are accepted, use-local-names-package should be 
supplied only when interpreting package prefixes. 

If name is a package, it is simply returned. 

If a list is supplied as name, it is interpreted as a specification of a package name and 
how to create it. 'Hie list should look like 
(name super-or-use size) 
or 

(name options) 

If name names a package, it is returned. Othenvisc a package is created by passing name 
and die o/;//o//s to make-package. 

% 

pkg-fInd-package name &optional create-p use^local-names-package 

Invokes find-package on name and returns tlie package that finds, if any. Otherwise, a 
package may be created, depending on create-p and possibly on how the user answers. 
These values of create-p are meaningful: 


nil 

An error is signaled if an existing package is not found. 

t 

A package is created, and returned. 


:find 

nil is returned. 


;ask 

The user is asked whether to create a package, 
package is created and returned. If he answers No, 

If he answers Yes, a 
nil is returned. 


If a package is created, it is done by calling make-package with name as the only 
argument. 

This function is not quite for historical compatibility only, since certain values of create-p 
provide useful features. 
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sys:package-not-found (error) Condiiion 

is signaled by pkg-find-package with second arguincni :error, nil or omitted, when the 
package docs not exist. 

I'he condition instance supports the operations :name and :relative-to; lliese return 
whatever was passed as the first and third arguments to pkg-find-package (the package 
name, and the package whose local nicknames should be searched). 

The pnK'ccd types tliat may be available include 

:retry says to search again for the specified name in case it has become defined; 

if it is still undefined, the error occurs again. 

:create-package 

says to search again for the specified name, and create a package with tliat 
name (and default characteristics) if none exists yet. 

:new-name is accompanied by a name (a string) as an argument, 'lliat name is used 
instead, ignoring any local nicknames. If tliat name too is not found, 
another error occurs. 

:no-action (available on errors from within read) says to continue with the entire 
read as well as is possible without having a valid package. 


27.9.1 I^cal Nicknames for Packages 

Suppose you wish to test new versions of the Chaosnet and file access programs. You could 
create new packages test-chaos and test-file-access, and use them for loading the new versions 
of the programs. ITien the old, installed versions would not be affected; you could still use them 
to edit and save the files of the new versions. But one problem must be solved: when the new 
file access program says "chaos:connect" it must get test-chaos:connect rather than the actual 
chaosxonnect 

This is accomplished by making "CHAOS” a local nickname for "TEST-CHAOS" in the 
context of the package test-file-access. This means that the when a chaos: prefix is 
encountered while reading in package test-file-access, it refers to test-chaos rather than 
chaos. 

Local nicknames are allowed to conflict with global names and nicknames; in fact, they are 
rarely useful unless they conflict. The local nickname takes precedence over tire global name. 

It is necessary to have a way to override local nicknames. If you (pkg-goto ’test-file- 
access), you may wish to call a function in chaos (to make use of the old, working Chaosnet 
program). This can be done using #: as die package prefix instead of just #: inhibits the 
use of local nicknames when it is processed. It always refers to the package which is globally the 
owner of the name that is specified. 

prefixes are printed whenever the package name printed is also a local nickname in the 
current package; that is, whenever an ordinary colon prefix would be misunderstood when read 
back 
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These arc the funciions which manage local nicknames. 

pkg-add-relat1ve-name in-pkg name forpkg 

Defines name as a local nickname m in-pkg for for pkg. in-pkg and for pkg may be 
packages, symbols or strings. 

pkg-delete-relatlve-name in-pkg name 
Hliminaies/wHtr as a local nickname in 

Looking up local nicknames is done with find-package, by providing a non-nil use-Iocal- 
names-package argument. 

27,10 Defining Packages 

Before any package can be referred to or made current, it must be defined. This is done 
with the special form defpackage, which tells tlie package system all sorts of things, including 
the name of the package, what packages it should use, its estimated size, and some of the 
symbols which belong in it. The defpackage form is recognized by Zmacs as a definition of the 
package name. 

defpackage name &key ... Macro 

Defines a package named name. The alternating keywords and values are passed, 
unevaluated, to make-package to specify tlie rest of tlie information about how to 
construct the package. 


If a package named name already exists, it is; modified insofar as this is possible to 
correspond to the new definition. 


Here are the possible options and their meanings 


nicknames 

size 

use 

prefix-name 

invisible 


A list of nicknames for the new package. The nicknames should be 
specified as strings. 

A number; the new package is initially made large enough to hold at least 
this many symbols before a rehash is needed. 

A list of packages or names for packages which the new package should 
inherit from, or a single name or package. It defaults to just the global 
package. 

Specifics the name to use for piinting package prefixes that refer to this 
package. It must be equal to eitlier the package name or one of the 
nicknames. 'Ihe default is to use the name. 

If non-nil, means that tliis package should not be put on the list *all- 
packages*. As a result, find-package will not find this package, not by 
its name and not by any of its nicknames. You can make normal use of 
the package in all other rcspcctis (passing it as the second argument to 
intern, passing it to use-package to make other packages inherit from it 
or it from others, and so on). 
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export 

iiniwrl 

shadow 

shadowing-import 

If any of these arguments is non-nil, it is passed to the function of llic 
same name, to operate on the package. Thus, if shadow is ("FOO" 
"BAR"), then 

(shadow ihis-package ’("FOO" "BAR")) 

is done. 


You could accomplish as much by calling export, import, shadow or 
shadowing-import yourself, but it is clearer to specify all such tilings in 
one central place, tlic defpackage. 

import-from 

If non-nil, is a list containing a package (or package name) followed by 
names of symbols to import from that package. Specifying import-from as 
(chaos "CONNECT" "LISTEN") is nearly the same as specifying import 
as (chaosrconnect chaosdisten), the difference being tliat with import- 
from the symbols connect and listen arc not looked up in the chaos 
package until it is time to import them. 

super 

If non-nil, should be a package or name to be the supcrpackage of the 
new package. ITiis means that the new package should inherit from that 
package, and also from all the packages that package inherits from. In 
addition, the supcrpackage is marked as autoexporting. Supcrpackages are 
obsolete and arc implemented for compatibility only. 

relative-names 

An alist specifying the local nicknames to have in this package for other 
packages. Each clement looks like {localname package), where package is 
a package or a name for one, and localname is the desired local 


nickname. 

relative-names-forme 

An alist specifying local nicknames by which this package can be referred 
to from other packages. Each element looks like {package localname), 
where package is a package name and localname is the name to refer to 
this package by from package. 

For example, the system package eh could have been defined this way: 

(defpackage "EH" :size 1200 

ruse ("GLOBAL" "SYS") :nicknames ("DBG" "DEBUGGER") 

:shadow ("ARG")) 

It has room initially for at least 1200. symbols, nicknames dbg and debugger, uses system as 
well as global, and contains a symbol named arg which is not the same as the arg in global. 
You may note that the function ehrarg is documented in this manual (see page 734), as is the 
function arg (see page 238). 

The packages of our inheritance example (page 642) might have been defined by 
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(defpackage ’chaos :size 1000 :use ’{sys global) 

:export ("CONNECT" "OPEN-STREAM" "LISTEN" ... 

"OPEN-STATE" "RFC-RECEIVED-STATE" ...)) 

(defpackage ’file-access :size 1500 
:use ’(chaos global) 

rexport ("OPEN-FILE" "CLOSE-FILE" "DELETE-FILE" ...) 

:import (chaos:connect chaos:open-state)) 

(defpackage ’mypackage :size 400 
;use ’(file-access global)) 

It is usually best to put die package definition in a separate file, which should be loaded into 
the user package. (It cannot be loaded into tlie package it is defining, and no other package has 
any reason to be preferred.) Often the files to be loaded into the package belong to one or a few 
systems; then it is often convenient to put the system definitions in Uic same file (sec chapter 28, 
page 660). 

A package can also be defined by the package attribute in a file’s -♦- line. Normally this 
specifies which (existing) package to load, compile or edit the file in. But if the attribute value is 
a list, as in 

-♦-Package: (foo :size 300 :use (global system)); ...-♦- 
tlicn loading, compiling or editing the file automatfcally creates package foo, if necessary with the 
specified options (just like defpackage options). No defpackage is needed. It is wise to use this 
feature only when the package is used for just a single file. For programs containing multiple 
files, it is good to make a system for them, and then convenient to put a defpackage near the 
defsystem. 

make-package name &kcy nicknames size use prefix-name invisible export shadow import 
shadowing-import import-from super relative-names relative-nameyfor-me 
Creates and returns new package with name name. 

The meanings of the keyword arguments are described under defpackage (page 652). 

pkg-create-package name &optional (super *package*) (s/ze#o200) 

Creates a new package named name of size size with superpackage super. This function is 
obsolete. 

kill - package name-or^package 

Kills tlie package specified or named. It is removed from the list which is searched when 
package names are looked up. 

package-declare \facro 

package-declare is an older way of defining a package, obsolete but still used, 
(package-declare name superpackage size nil 
option-1 option-2 , ..) 

creates a package named name with initial size size. 
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.v«/«r specifies \hc supcrpackagc to use for this package. Stipcrpackages were an old way 
of "specifying inheriuince: it was transitive, all symbols were inherited, and only one 
inheritance path could exist. If super h global, nothing special needs to be done; 
otherwise, die old superpackage facility is simulated using die super argument to make- 
package. 

body is now allowed to contain only these types of elements: 

(shadovv names) 

Piisses the names to the function SHADOW. 

(intern names) Converts each name to a string and interns it in the package. 

(refname refname packagename) 

Makes refname a local nickname in diis package for the package named 
packagename. 

(myrefname packagename refname) 

Makes refname a local nickname in the package named packagename for 
diis package. \f packagename is "GLOBAL", makes refname a global 
nickname for this package. 

(external names) 

Docs nothing, 'fhis controlled an old feature that no longer exists. 


27.11 Operating on All the Symbols in a Package 

To find and operate on every symboT present or available in a package, you can choose 
between iteration macros that resemble dolist and mapping functionals that resemble mapear. 

Note that all constructs that include inherited symbols in the iteration can process a symbol 
more than once. This is because a symbol can be directly present in more than one package. If 
it is direedy present in the specified package and in one or more of the used packages, the 
symbol is processed once each time it is encountered. It is also possible for the iteradon to 
include a symbol that is not actually available in the specified package. If that package shadows 
symbols present in the packages it uses, the shadowed symbols are processed anyway. If this is a 
problem, you can explicidy use intern-soft to see if the symbol handed to you is really available 
in the package. This test is not done by default because it is slow and rarely needed. 

do-symbols (yar package result-form) body... Macro 

Executes body once for each symbol findable in package either directly or through 
inheritance. On each iteration, the variable var is bound to the next such symbol. Finally 
the result-form is executed and its values are returned. 

do-local-symbols {var package result-form) body... Macro 

Executes body once for each symbol present dircedy in package. Inherited symbols are 
not considered. On each iteradon, the ; variable var is bound to the next such symbol. 
E'inally the result-form is executed and its values are returned. 
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do-extornal-symbols {var package result-form) body... Macro 

Hxccutcs body once for each external symbol findable in package either directly or through 
inheriutnee. On each iteration, tlie variable var is bound to die next such symbol. Finally 
die rcsuU-fortn is executed and its values are returned. 

do-local-external-symbols (vflr /wcAv/gc body... Macro 

Hxecutes body once for each external symbol present directly in package. Inherited 
symbols are not considered. On each iteration, die variable var is bound to the next such 
symbol. I'inally die result-form is executed and its values are returned. 

do-all-symbols (var result-form) body... Macro 

P.xecutes body once for each symbol present in any package. On each iteration, the 
variable var is bound to die next such symbol, f'inally the result-form is executed and its 
values are returned. 

Since a symbol can be directly present in more than one package, it is possible for the 
same symbol to be processed more than once. 

mapatoms function &optional (package*package*) (inherited-pt) 

function should be a function of one argument, mapatoms applies Junction to all of the 
symbols in package. If inherited-p is non-nil, then the function is applied to all symbols 
available in package, including inherited symbols. 

mapatoms-all function &opuonal (/wcAroge "GLOBAL") 

/wz/c/Zo/i should be a function of one argument, mapatoms-all applies function to all of 
the symbols in package and all other packages which use package. 

It is used by such functions as apropos and who-calls (see page 791) 

Example: 

(mapatoms-all 
^’(lambda (x) 

(and (alphalessp ’z x) 

(print X)))) 

27.12 Packages as Lisp Objects 

A package is a conceptual name space; it is also a Lisp object which serves to record the 

contents of that name space, and is passed to functions such as intern to identify a name space. 

packagep object 

X if object is a package. 

•all-packages* Variable 

'fhe value is a list of all packages, except for invisible ones (see the invisbie argument to 
make-package, page 654). 
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llst-all-packages 

A Common Lisp function which returns *all-packages*. 

pkg-global-package Constant 

pkg-system-package Constant 

pkg-keyword-package Constant 

Respectively, the packages named global, system and keyword. 

descrIbe-package package 

Prints everything there is to know about package, except for all the symbols interned in 
it. package can be specified as a package or as the name of one. 

'I'o see all the symbols interned in a package, do 
(inapatoms ’print package) 


27.13 Common Lisp and Packages 

Common Lisp docs not have defpackage or lines in files. One is supposed to use the 
function in-package to specify which package a file is loaded in. 

1n-package name &key nicknames use 

Creates a package named name, with specified nicknames and used packages, or modifies 
an existing package named name to have those nicknames and used packages. 

ITicn ‘package* is set to this package. 

Writing a call to in-package at the beginning of the file causes ‘package* to be set to that 
package for the rest of the file. 

If you wish to use this technique for the sake of portability, it is best to have a -*- line 
with a package attribute also. While in-package does work for loading and compilation of the 
file, Zmacs docs not respond to it. 

In Common Lisp, the first argument to intern or find-symbol is required to be a symbol. 

27.14 Initialization ofthc Package System 

'fhis section describes how the package system is initialized when generating a new software 
release of the Lisp Machine system; none of this should affect users. 

ITie cold load, which contains the irreduceable minimum of the Lisp system needed for 
loading the rest, contains the code for packages, but no packages. Before it begins to read from 
the keyboard, it creates all the standard packages based on information in si:initial-packages, 
applying make-package to each element of it. At first all of the packages are empty. The 
symbols which belong in the packages global and system are recorded on lists which are made 
from the files SYS: SYS2: GLOBAL LISP and SYS: SYS2; SYSTEM LISP. Symbols referred 
to in the cold load which belong in packages other than si have strings (package names) in their 
package slots; scanning through the area which contains all the symbols, the package initializer 
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puts each such symbol into the packtige it specifics, an<l all tltc rest into si unless tlicy arc already 
in global or system. 

27.15 Initial Packages 

The initially present packages include: 
global Contains advertised global functions, 

user The dcfiiult current package for die user’s type-in. 

sys or system Contains intcriiiil global symbols used t)y various system programs. Many system 
packages use system. 

si or system-internals 

Contains subroutines of many advertised system functions. Many files of the Lisp 
system arc loaded in si. 

compiler Contains the compiler, compiler uses sys. 
fs or file-system 

Contains the code that deals with pathnames and accessing files, fs uses sys. 
eh or dbg Contains the error handler and the debugger. Uses sys. 

cc or cadr Contains the program that is used for debugging another machine. Uses sys. 

chaos Contains the Chaosnet controller. Uses sys. 

tv Contains the window system. Uses sys. 

zwei Contains the editor. 

format Contains the function format and its associated subfunctions. 

cli (Common Lisp Incompatible) contains symbols such as cli:member which the 

same pname as symbols in global but incompatible definitions. 

There are quite a few others, but it would be pointless to list them all. 

Packages that are used for special sorts of data: 
fonts Contains the names of all fonts, 

format Contains the keywords for format, as well as the code. 

keyword Contains all keyword symbols, symbols always written with a plain colon as a 

prefix. These symbols are peculiar in that they arc automatically given themselves 
as values. 

Here is a picture depicting the initial package inheritance structure 
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28. Maintaining Large Systems 

When a program gets large, it is often desirable to split it up into several files. One reason 
for tills is to help keep tlie parts of the program organized, to make tilings easier to find. It's 
also useful to have the program broken into small pieces that are more convenient to edit and 
compile. It is particularly important to avoid tlic need to recompile all of a large program every 
time any piece of it changes; if Uic program is broken up into many files, only the files that 
have changes in tlicm need to be recompiled. 

riic apparent drawback to splitting up a program is tliat more commands tire needed to 
maiiipulaie it. To load tlie program, you now have to load several files scpttratcly, instead of just 
loading one file. To compile it. you have to figure out which files need compilation, by seeing 
which have been edited since they were last compiled, and then you have to compile tliosc files. 

What's even more complicated is that files can have interdependencies. You might have a file 
called DEFS tliat contains some macro definitions (or flavor or structure definitions), and functions 
in other files might use those macros. This means that in order to compile any of tliose other 
files, you hiust first load the file DEFS into tlie I .isp environment so diat the macros will be 
defined and can be expanded at compile time. You have to remember this whenever you compile 
any of tliosc files. Furthennore, if DEFS has changed, otlicr files of the program may need to be 
recompiled because the macros may have changed and need to be re-expanded. 

ITiis chapter describes the system facility, which takes care of all these things for you. The 
way it works is that you define a set of files to be a system, using the defsystem special form, 
described below. This system definition says which files make up the system, which ones depend 
on die presence of others, and so on. You put this system definition into its own little file, and 
then all you have to do is load diat file and die Lisp environment will know about your system 
and what files arc in it. You can then use the make-system function (sec page 666) to load in 
all die files of the system, recompile all the files that need compiling, and so on. 

The system facility is very general and extensible. This chapter explains how to use it and 
how to extend it. This chapter also explains the patch facility, which lets you conveniently update 
a large program with incremental changes. 

28.1 Defining a System 

defsystem name (keyword args...)... Macro 

Defines a system named name. The options selected by the keywords are explained in 
detail later. In general, they fall into two categories: properties of the system and 
transformations. A transformation is an operation such as compiling or loading that takes 
one or more files and docs something to them. The simplest system is a set of files and a 
transformation to be performed on them. 

Here arc a few examples. 
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(defsystem mysys 




(:coinpile-load ("0Z:<GE0RGE>PR0G1.LISP" "OZ:<GEORGE2>PROG2.LISP"))) 

(defsystem zmail 
(:name "ZMail") 

(:pathname-default "SYS: ZMAIL;") 

(:package zwei) 

{:iTiodule defs "DEES") 

(:modu1e mult "MULT" rpackage tv) 

(:module main ("TOP" "COMNDS" "MAIL" "USER" "WINDOW" 

"FILTER" mult "COMETH")) 

(:compile-load defs) 

{:compile-load main (-.fasload defs))) 

(defsystem bar 

(:modu1e reader-macros "BAR:BAR;RDMAC") 

(:modu1e other-macros "BAR:BAR;MACR0S") 

(imodule main-program "BAR:BAR;MAIN") 

{:compile-load reader-macros) 

(:compile-1oad other-macros (rfasload reader-macros)) 

(:compile-1oad main-program (:fas1oad reader-macros 

other-macros))) 

I’hc first example defines a new system called mysys, which consists of two files, stored on a 
Tops-20 host names OZ, both of which are to be compiled and loaded. The second example is 
somewhat more complicated. What all the options mean is described below, but the primary 
difference is that there is a file DEFS which must be loaded before the rest of the files (main) 
can be compiled. Also, the files are stored on logical host SYS and directory ZMAIL, 

'fhe last example has two levels of dependency, reader-macros must be compiled and 
loaded before other-macros can be compiled. Both reader-macros and other-macros must 
then be loaded before main-program can be compiled. All the source files are stored on host 
BAR, presumably a logical host defined specifically for this system. It is desirable to use a logical 
host for the files of a system if there is a chance that people at more than one site will be using 
it; the logical host allows the identical defsystem to be valid at all sites. See section 24.7.5, page 
572 for more on logical hosts and logical pathnames. 

Note that The defsystem options other than transformations are: 

;name Specifies a “pretty” version of the name for the system, for use in printing. 

;short-name 

Specified an abbreviated name used in constructing disk label comments and in patch file 
names for some file systems. 

:component-systems 

Specifies the names of other systems used to make up tliis system. Performing an 
operation on a system with component systems is equivalent to performing the same 
operation on all the individual systems. ITic format is (-.component-systems names...). 
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:package 

Specifics the package in which transformations arc performed. A package specified here 
overrides one in the line of tlic file in question. 

:pathname-default 

Gives a local default within the definition of tJic system for-strings to be parsed into 
pathnames, fypically this specifics die directory, when all tlic files of a system arc on Uie 
same directory. 

iwarnings-pathname-default 

Gives a default for tlic file to use to store compiler warnings in, when make-system is 
used with the :batch option. 

:patchable 

Makes tlic system be a patchabic system (see section 28.8, page 672). An optional 
argument specifics the directory to put patch files in. 'fhc default is die :pathname- 
default of die system. 

:initial-stjllUa 

Specifics what the status of the system should be when make-system is used to create a 
new major version. The default is :experimental. Sec section 28.8.5, page 679 for further 
details. 

:not-in-disk-label 

Make a patchabic system not appear in the disk label comment. This should probably 
never be specified for a user system. It is used by patchabic systems internal to the main 
Lisp system, to avoid cluttering up the label. 

:default-binary-file-type 

Specifics the file type to use for compiled Lisp files. The value you specify should be a 
string. If you do not specify this, die standard file type :qfasl is used. 

:module 

Allows assigning a name to a set of files within the system. This name can then be used 
instead of repeating the filenames. The format is (:module mme files options...), files is 
usually a list of filenames (strings). In general, it is a module-specification, which can be 
any of the following: 

a string 

This is a file name, 
a symbol 

ITiis is a module name.. It stands for all of the files which are in that module of 
this system. 

an external module component 

Tliis is a list of the form (system-name module-names...), to specify modules in 
anodicr system. It stands for all of the files which arc in all of those modules. 

a list of module components 

A module component is any of the above, or the following: 
a list of file names 

I'his is used in the case where the names of the input and output files of a 
transformation are not related according to the standard naming conventions, for 
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example when a Ql-ASl. file has a dilTcrcnt name or resides on a different 
directory than the source file. The file names in the list are used from left to 
right, thus the first name is the source file. l'.ach file name after die first in tlie 
list is defaulted from tlie previous one in the list. 

To avoid syntactic ambiguity, this is allowed as a module component but not as a 
module specification. 

The currently defined options for the :module clause arc 

;package Overrides any package specified for tlic whole system for transformations 
performed on just this module. 

In the second defsystem example above, tlicre are tlircc modules. Hiich of tlie first two 
has only one file, and the tliird one (main) is made up both of files and another module. 

To take examples of die other possibilities, 

(:module prog (("SYS: GEORGE; PROG" "SYS: GE0RG2: PROG"))) 
(:module foo (defs (zmail defs))) 

me prog module consists of one file, but it lives in two directories, GEORGE and 
GEORG2. If this were a Lisp program, that would mean diat the file SYS: GEORGE; 
PROG LISP would be compiled into SYS: GEORG2; PROG QFASL. Ihe foo module 
consists of two other modules the defs module in the same system, and die defs module 
in the zmail system. It is not generally useful to compile files that belong to other 
systems; thus this foo module would not normally be the subject of a transformation. 
However, dependencies (defined below) use modules and need to be able to refer to 
(depend on) modules of other systems, 

si :s 0 t-systetn-source-f lie system-name filename 

'Hiis function specifies which file contains the defsystem for the system system-name, 
filename can be a pathname object or a string. 

Sometimes it is useful to say where the definition of a system can be found without 
taking time to load that file. If make-system, or require (page 672), is ever used on 
that system, the file whose name has been specified will be loaded automatically. 


28.2 Transformations 

Transformations are of two types, simple and complex. A simple transformation is a single 
operation on a file, such as compiling it or loading it. A complex transformation takes die output 
from one transformation and performs another transformation on iL such as loading the results of 
compilation. 

The general format of a simple transformation is (name input dependencies condition), input is 
usually a module specification or another transformation whose output is used. The transformation 
name is to be performed on all the files in the module, or all the output files of the other 
transformation. 
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dcpcmkncics and condilion arc optinnal. 

dependencies is a Irdnsfonnalion specification, either a list (transfonnation-name module- 
names...) or a list of such lists. A module-name is citlicr a symbol lliat is tlic name of a module 
in the current system, or a list {system-name module-names...). A dependency declares that all of 
tlic indicated transformations must be performed on the indicated modules before the current 
transformation itself can take place. Thus in the /.mail example above, the defs module must 
liave the ifasload transformation performed on it before die xompile transfonnation can be 
performed on main. 

Tlie dependency has to be a tranformation Uiat is explicitly specified as a transformation in 
the system definition, not just an action that might be performed by anything. That is, if you 
have a dependency (dasload foo), it means that (fasloeid foo) is a tranformation of your system 
and you depend on that tranformation; it does not simply mean that you depend on foo’s being 
loaded. Kurthennorc. it doesn’t work if (dasload foo) is an implicit piece of another 
tranformation, For example, the following works; 

('Icif system foo 

(imodule foo "FOO") 

(:modu1e bar "BAR") 

(:compile-load (foo bar))) 
but this doesn’t work: 

(defsystem foo 

(imodule foo "FOO") 

(:inodule bar "BAR") 

{imodule blort "BLORT") 

(:compile-load (foo bar)) 

(:compilG-load blort (ifasload foo))) 

because foo’s dasload is not mentioned explicitly (i.e. at top level) but is only implicit in the 
(xompile-load (foo bar)). One must instead write: 

(defsystem foo 

(:module foo "FOO") 

(imodule bar "BAR") 

(:module blort "BLORT") 

(:compile-load foo) 

(;compile-load bar) 

(:compile-load blort (ifasload foo))) 

condition is a predicate which specifies when the transformation should take place. Generally 
it defaults according to the type of tlie transformation. Conditions arc discussed further on page 
671. 


The defined simple transformations are: 

:fasload Calls the fasload function to load the indicated files, which must be QFASL files 
whose patlmamcs have canonical type :qfasl (see section 24.2.3, page 551). The 
condition defaults to si:file-newer-than-installed-p, which is t if a newer version 
of the file exists on the file computer than was read into the current environment 
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:readfile Calls ilic readfile function to read in the indicated files, whose names must have 
canonical type :lisp. Use tliis for files that arc not to be compiled. cuiuJilion 
defaults to si:file-newer-than-installed-p. 

icompile Calls tlic compile-file function to compile the indicated files, whose names must 
have canonical type ilisp. amiition defaults to si;file-newer-than-file-p, which 
returns t if the source file has been written more recently than the binary file. 

A special simple transformation is 
:do-components 

(:do-components inside a system with component systems causes 

the dcpcndcm'ies to be done before anything in the component systems. This is 
useful when you have a module of macro files used by all of die component 
systems. 

'flic defined complex transformations are 

:compile-load (;compile-load inpul compile-dcpendcncies load-dependencies conipile-eondilion load- 
condition) is the same as (dasload (rcompile inpul compile-dependencies compile- 
condition) load-dependencies load-condition). This is the most commonly-used 
transformation. Everything after input is optional. 

:compile-load-init 

See page 671. 

As was explained above, each filename in an input specification can in fact be a list of strings 
when the source file of a program differs from the binary file in more tlian just the file type. In 
fact, every filename is treated as if it were an infinite list of filenames with the last filename, or 
in the case of a single string the only filename, repeated forever at the end. Each simple 
transformation takes some number of input filename arguments and some number of output 
filename arguments. As transformations are perfonned, these arguments arc taken from the front 
of the filename list. 'Fhe input arguments are actually removed and the output arguments left as 
input arguments to the next higher transformation. To make tltis clearer, consider the prog 
module above having the :compile-load transformation performed on it. ITiis means that prog is 
given as the input to the :compile transformation and the output from this transformation is given 
as the input to the ifasload transformation. The :compile transformation takes one input filename 
argument, the name of a Lisp source file, and one output filename argument, the name of the 
QFASL file. 'ITic dasload transformation takes one input filename argument, the name of a 
QFASL file, and no output filename arguments. So, for tlic first and only file in the prog 
module, tlic filename argument list looks like ("SYS: GEORGE; PROG" "SYS: GEORG2; 
PROG" "SYS: GEORG2; PROG" ...). ITie :compile transformation is given arguments of 
"SYS: GEORGE; PROG" and "SYS: GEORG2; PROG" and the filename argument list which 
it outputs as the input to the :fasload transformation is ("SYS: GEORG2; PROG" "SYS: 
GEORG2; PROG" ...). The :fasload transformation then is given its one argument of "SYS: 
GEORG2; PROG". 

Note that dependencies are not transitive or inherited. For example, if module a depends on 
macros defined in module b, and therefore needs b to be loaded in order to compile, and b has 
a similar dependency on c, c need not be loaded for compilation of a. Transformations with 
these dependencies would be written 
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(:compile-load a (:fas load b)) 

(:compile-load b (ifasload c)) 

To say that compilation of a depends on both b and c,.you would instead write 
(:compile-load a (:fas1oad b c)) 

(:compile-load b (:fasload c)) 

IF in addition a depended on c (but not b) during loading (perhaps a contains defvars whose 
initial values depend on functions or special variables defined in c) you would write the 
transformations 

(:compile-load a (:fasload b c) (:fasload c)) 

(:compile-load b (:fasload c)) 

28.3 Making a System 

make-system name &rcst keywords 

The make-system function docs the actual work of compiling and loading. In the 
example above, if PROGi and PROG2 have both been coir|pilcd recently, then 
(make-system ’mysys) 

loads dicm as necessary. If cither one might also need to be compiled, then 
(make-system ’mysys :compile) 
docs that first as necessary. 

The very first tiling make-system docs is check whether the file which contains the 
defsystem for the specified system has changed since it was loaded. If so, it offers to 
load the latest version, so tliat Uic remainder of tlic make-system can be done using the 
latest system definition. (Ihis only happens if the filctype of tliat file is LISP.) After 
loading this file or not, make-system goes on to process tlie files that compose the 
system. 

If the system name is not recognized, make-system attempts to load the file SYS: SITE; 
system-name SySTEU, in tlie hope that that contains a system definition or a call to 
si ;set-system-source-file. 

make-system lists what transformations it is going to perform on what files, then asks 
the user for confinnation. If the user types S when confirmation is requested, then 
make-system asks about each file individually so that the user can decide selectively 
which transformations should be perfonned; then collective reconfirmation is requested. 
This is like what happens if tlie :selective keyword is specified. If the user types Y, the 
transformations are performed. Before each tranfformation a message is printed listing the 
transformation being perfonned, the file it is being done to, and the package. This 
behavior can be altered by A:e>’»vor^/s. 

If the system being made is patchable, and if loading has not been inhibited, then the 
system’s patches arc loaded afterward. Loading of patches is silent if tlie make-system is, 
and requires confirmation if the make-system does. 

Hicse are the keywords recognized by the make-system function and what they do. 

:noconfirm Assumes a yes answer for all questions that would otherwise be asked of the user. 
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:selective Asks the user whether or not to pcrfonTi c.icli translormation that appears to be 
needed for eiich file. 

isilent Avoids priming out each transfonnation as it is performed. 

:reload Bypasses the specified conditions for performing a tninsformation. 'finis files are 

compiled even if they haven't changed and loaded even if they aren't newer than 
tlie instikJied version. 

;noload Docs nm load any files except those required by dependencies. Kor use in 

conjunctHin with tlie xompile option. 

rcompile Compiles files also if need be. fhe default is to load but not compile. 

recompile I’his is equivalent to a combination of xompile and rreload: it specifics 

compilation of all files, even those whose sources have not changed since last 
compiled. 

:no-increment-patch 

When given along with the xompile option, disables the automatic incrementing ■ 
of the major system version that would otherwise take place. Sec section 28.8, 
page 672. 

:increment-patch 

Increments a patchablc system’s major version without doing any compilations. 
Sec section 28.8, page 672. 

:no-reload-system-declaration 

Turns off the check for whether the file containing the defsystem has been 
changed. Then the file is loaded only if it has never been loaded before. 

:batch Allows a large compilation to be done unattended. It acts like moconfirm with 

regard to questions, turns off more-processing and fdcfinc-warnings (sec inhibit- 
fdefine-warnings, page 240), and saves tlie compiler warnings in an editor buffer 
and a file (it asks you for the name). 

:defaulted-batch 

'This is like :batch except that it uses the default for the pathname to store 
warnings in and does not ask the user to type a pathname. 

:print-only Just prints out what transformations would be performed; does not actually do 
any compiling or loading. 

;noop Is ignored. This is useful mainly for programs that call make-system, so that 

such programs can include forms like 

(make-system ’mysys (if compile-p :compne :noop)) 
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28.4 Addins New Keywords to make-system 

make-system keywords are defined as functions on the si:make-system-keyword property of 

the keyword. The functions arc called with no arguments. Some of tlic relevant variables they 

can use are 

s1: •system-being-made* Variable 

The internal data structure that represents the system being made. 

s1: •make-system-forms-to-be-evaled-before* Variable 

A list of forms that are evaluated before the transfonnations arc performed. 

si: •make-system-forms-to-be-evaled-after* Variable 

A list of fonns that arc evaluated after th<; transfonnations have been performed. 
Transformations can push entries here too. 

si: •make-system-forms-to-be-evaled-f inally* Variable 

A list of fonns that arc evaluated by an unwind-protect when die body of make-system 
is exited, whether it is completed or not. Closing the batch warnings file is done here. 
Unlike the si;*make-system-forms-to-be-evaled-after* forms, these forms are 
evaluated outside of the “compiler warnings conte;xt”. 

si: ♦query-type* . Variable 

Controls how questions are asked. Its normal value is inormal. moconfirm means ask no 
questions and :selective means asks a question for each individual file transformation. 

si :*sil8nt-p* Variable 

If t, no messages are printed out. 

si :*batch-mod 0 -p* Variable 

If t, :batch was specified. 

s1:*redo-an* Variable 

if t, all transformations are performed, regardless of the condition functions. 

si: *top-l0vel-transformat1ons* Variable 

A list of the types of transformations that should be performed, such as (dasload 
ireadfile). Ibc contents of this list arc controlled by the keywords given to make- 
system. This list then controls which transformations are actually performed. 

si :*fi l 0 -transformation-f unction* Variable 

The actual function that gets called with the list of transformations that need to be 

performed. ITic default is si:do-file-transformations. 

si:define-make-system-special-variable variable value [dejvar-p] Macro 

Causes variable to be bound to value during the body of the call to make-system. This 
allows you to define new variables similar to those listed above, value is evaluated on 
entry to make-system. If defvar-p is specified as (or defaulted to) t, variable is defined 
with defvar. It is not given an initial value. If dejvar-p is specified as nil, variable 
belongs to some other program and is not defvar’ed here. 
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I'hc following simple example adds a new keyword to make-system called :just-warn, which 
means that fdefine warnings (sec page 239) regarding functions being overwritten should be 
printed out, but tlic user should not be queried. 

(si:define-make-system-special-variable 

inhibit-fdefine-warnings inhibit-fdefinerwarnings nil) 

(defun (:just-warn si:make-system-keyword) () 

(setq inhibit-fdefine-warnings :just-warn)) 

(Sec die description of the inhibit-fdefine-warnings variable, on page 240.) 

make-system keywords can do something directly when called, or they can have tlicir effect 
by pushing a form to be evaluated onto si:*make-system-forms-to-be-evaled-after* or one of 
the other two similar lists. In general, the only useful thing to do is to set some special variable 
defined by si:define-make-system-special-variable. In addition to the ones mentioned above, 
user-defined transformations may have their behavior controlled by new special variables, which 
can be set by new keywords. If you want to get at the list of transfonnations to be performed, 
for example, the right way is to set si:*file-transformation-function* to a new function, which 
tlien can call si:do-file-transformations with a possibly modified list. 'I’hat is how tlie ;print- 
only keyword works. 


28.5 Adding New Options for defsystem 

Options to defsystem are defined as macros on the si :defsystem-macro property of the 
option keyword. Such a macro can expand into an existing option or transformation, or it can 
have side effects and return nil. There are several variables they can use; the only one of general 
interest is 

si: •system-being-defined* Variable 

The internal data structure that represents the system that is currently being constructed. 

si:defIne-defsystem-speclal-varlable variable value Macro 

Causes value to be evaluated and variable to be bound to the result during the expansion 
of the defsystem special form. ITtis allows you to define new variables similar to the one 
listed above. 

si;def1ne-s1mp1e-transfopmat1on Macro 

This is the most convenient way to define a new simple transformation. The form is 
(si :define-simple-transformation name junction 
default-condition inpul-file-types output-file-types 
pretty-names compile-like load-like) 

For example, 

(si:define-simple-transformatlon icompile si:qc-file-l 
si:file-newer-than-file-p (:lisp) (:qfasl)) 
input-file-types and output-file-types are how a transformation specifies how many input 
filenames and output filenames it should receive as arguments, in this case one of each. 
They also, obviously, specify the default file type for these pathnames. The si:qc-file-1 
function is mostly like compile-file, except for its interface to packages. It takes input- 
file and output-file arguments. 
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prelly-iHinicx, conipile-like, and loiul-like arc optional. 

preiiy-iiamcs specifics how messages printed for the user should print die name of the 
transformation. It can be a list of the impenitivc ("Compile”), the present participle 
(“Compiling"), and die past participle ("compiled"). Note that die past participle is not 
capilali/cd, because when used it docs not come at the beginning of a sentence, pretty 
names can be just a string, which is taken to be the imperative, and die system will 
conjugate the participles itself. 11 pretty-names is omitted or nil it defaults to the name of 
the transformation. 

compile-like and load-like say when die transformation should be perfonned. Compile-like 
transforinaiions arc performed when the xompile keyword is given to make-system. 
Load-like transformations arc performed unless the rnoload keyword is given to make- 
system. By default compile-like is t but load-like is nil. 

Complex transformations arc defined as normal macro expansions, for example, 

(defmacro ( :coinpile-1oad si rdefsystem-macro) 

(input &optiona1 com-dep load-dep 

cora-cond load-cond) 

'{ifasload {;compile .input ,com-dep ,com-cond) 

,load-dep ,load-cond)) 

28.6 More Esoteric Transformations 

It is sometimes useful to specify a transformation upon which somcdiing else can depend, but 
which is performed not by default, but rather only when requested because of diat dependency. 
I’he transfonnation nevertheless occupies a specific place in the hierarchy, flic :skip defsystem 
macro allows specifying a transformation of this type. For example, suppose there is a special 
compiler for the read table which is not ordinarily loaded into die system. The compiled version 
should still be kept up to date, and it needs to be loaded if ever the read table needs to be 
recompiled. 

(defsystem reader 

(;pathname-default "SYS: 10;") 

(:package system-internals) 

(:module defs "RDDEFS") 

(:module reader "READ") 

(:module read-table-compiler "RTC") 

(:module read-table "RDTBL") 

( :coinpile-load defs) 

(:compile-load reader (rfasload defs)) 

(:skip :fasload (icompile read-table-compiler)) 

(:rtc-compi1e-1oad read-table (ifasload read-table-compiler))) 
Assume that dicre is a complex transformation :rtc-compile-load, which is like ;compile-load 
except diat is is built on a transformation called something like :rtc-compile. whieh uses the read 
table compiler rather than the Lisp compiler. In the above system, dicn, if the :rtc-compile 
transfonnation is to be performed, die dasload transfonnation must be done on read-table- 
compiler first, that is the read Uible compiler must be loaded if the read table is to be 
recompiled. If you say (make-system ’reader xompile), then die xompile transformation is 
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done on the read-table-compiler module despite die :skip, compiling the read table compiler if 
need be. If you say (make-system ’reader), the reader and the read table arc loaded, but tlic 
:skip keeps this from happening to the read table compiler. 

So far nothing has been said about what can be given as a comlidon for a transformation 
except for tlic default functions, which check for conditions such as a source file being newer 
than die binary. In general, any function that takes the same arguments as the transfonnation 
function (e.g. compile-file) and returns t if the transformation needs to be performed, can be in 
this place as a syndiol, including for example a closure. I'o take an example, suppose there is a 
fde that contains compile-flavor-methods for a system and diat should therefore be recompiled 
if any of die flavor method definitions change. In this case, the condition function for compiling 
diat file should return t if eidier die source of that file itself or any of die files that define die 
flavors have changed. Hiis is what die :compile-load-init complex transformation is for. It is 
defined like diis: 

(defmacro (:compile-load-init si:defsystem-macro) 

(input add-dep &optional com-dep load-dep 
&aux function) 

(setq function (let-closed ((♦additional-dependent-modules* 

add-dep)) 

’compile-load-init-condition)) 

'(:fasload (.‘compile .input ,com-dep .function) .load-dep)) 

(defun compile-load-init-condition (source-file qfasl-file) 

(or (si:file-newer-than-file-p source-file qfasl-file) 

(local-declare ((special ♦additional-dependent-modules*)) 

(si:other-files-newer-than-file-p 

♦additional-dependent-modules* 
qfasl-file)))) 

The condition function generated when this macro is used returns t either if si:file-newer- 
than-file-p would with those arguments, or if any of the other files in add-dep, which 
presumably is a module specification, are newer than the QFASL file. Thus the file (or module) 
to which the :compile-load-init transformation applies will be compiled if it or any of the source 
files it depends on has been changed, and will be loaded under the normal conditions. In most 
(but not all cases), com-dep is a dasload transfonnation of the same files as add-dep specifies, 
so that all the files this one depends on will be loaded before compiling it. 

28.7 Common Lisp Modules 

In Common Lisp, a module is a name given to a group of files of eode. Modules are not 
like systems because nothing records what the “contents” of any particular module may be. 
Instead, one of the files which defines the module contains a provide form which says, when that 
file is loaded. “Module foo is now present” Other files may say, using require, “I want to use 
module foo.” 

Normally the require form also specifies the files to load if foo has not been provide’d 
already. ITiis is where the information of which files are in a module is stored. If the require 
does not have file names in it, the module name foo is used in an implementation-dependent 
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manner to find files to load. The Lisp Machine does this by using it as a system name in make- 
system. 

provide module-name 

Adds module-name to tlie list ‘modules* of modules already loaded, module-name should 
be a string; case is significant. 

require module-name &rcst files 

If module module-name is not already loaded (on ‘modules*), files tire loaded in order to 
make the module available, module-name should be a string; case is significant. The 
elements of files should be pathnames or namestrings. If files is nil, (make-system 
module-name .-noconfirm) is done. Note, however, tliat case is not significant in the 
argument to make-system. 

•modules* Variable 

A list of names (strings) of all modules provide’d so far. 

28.8 The Patch Facility 

(he patch facility allows a system maintaincr to manage new releases of a large system and 
issue patches to correct bugs. It is designed to be used to maintain both die Lisp Machine system 
itself and applications systems tliat are large enough to be loaded up and saved on a disk 
partition. 

When a system of programs is very large, it needs to be maintained. Often problems are 
found and need to be fixed, or other little changes need to be made. However, it takes a long 
time to load up all of die files that make up such a system, and so radier than having every user 

load up all die files every dme he wants to use die system, usually the files just get loaded once 

into a Lisp world, which is then saved away on a disk partition. Users then use this disk 

partition, copies of which may appear on many machines. The problem is that since the users 

don’t load up the system every time they want to use it, they don’t get all the latest changes. 

I'he purpose of the patch system is to solve this problem. A patch file is a little file that, 
when you load it, updates the old version of the system into the new version of the system. 
Most often, patch files Just contain new function definitions; old fimetions are redefined to do 
dicir new diing. When you want to use a system, you first use the Lisp environment saved on 
die disk, and then you load all the latest patches. Patch files are very small, so loading them 
doesn’t take much time. You can even load the saved environment, load up the latest patches, 
and dien save it away, to save future users the trouble of even loading die patches. (Of course, 
new patches may be made later, and then these will have to be loaded if you want to get the 
very latest version.) 

For every system, there is a series of patches that have been made to that system. To get the 
latest version of the system, you load each patch file in the series, in order. Sooner or later, the 
maintaincr of a system wants' to stop building more and more patches, and recompile everything, 
starting afresh. A complete recompilation is also necessary when a system is changed in a far- 
reaching way, that can’t be done with a small patch; for example, if you completely reorganize a 
-program, or change a lot of names or conventions, you might need to completely recompile it to 
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make it work again. After a complete recompilation has been done, the old patch files arc no 
longer suitable to use; loading them in might even break things. 

’llic way all this is kept track of is by labelling each version of a system with a two-part 
number. 'I’he two parts arc called the major version number and the minor version number, llie 
minor version number is increased every time a new patch is made; the patch is identified by tlie 
major and minor version number together. I'he major version number is increased when tlic 
program is completely recompiled, and at that time tlic minor version number is reset to zero. A 
complete system version is identified by the major version number, followed by a dot, followed 
by tlic minor version number. Thus, patch 93.9 is for major version 93 and minor version 9; it 
is followed by patch 93.10. 

'I'o clarify this, here is a typical scenario. A new system is created: its initial version number 
is 1.0. Then a patch file is created; die version of the program that results from loading the first 
patch file into version 1.0 is called 1.1. fhen another patch file might be created, and loading 
tliat patch file into system 1.1 creates version 1.2. Then tlic entire system is recompiled, creating 
version 2.0 from scratch. Now tlic two patch files arc irrelevant, because they fix old software; 
tlic changes tliat they reflect arc integrated into system 2.0. 

Note that the second patch file should only be loaded into system 1.1 in order to create 
system 1.2; you shouldn't load it into 1.0 or any other system besides 1.1. It is important that 
all die patch files be loaded in the proper order, for two reasons. Hirst, it is very useful diat any 
system numbered 1.1 be exaedy the same software as any other system numbered 1.1, so that if 
somebody reports a bug in version 1.1, it is clear just which software is being complained about. 
Secondly, one patch might patch another patch; loading them in some other order might have 
the wrong effect. 

The patch facility keeps track of all die patch files that exist, remembering which version each 
one creates. There is a separate numbered sequence of patch files for each major version of each 
system. All of them are stored in the file system, and the patch facility keeps track of where they 
all arc. In addition to the patch files diemselves, there arc patch directory files that contain the 
patch facility’s data base by which it keeps track of what minor versions exist for a major version, 
and what the last major version of a system is. ITiese files and how to make them are described 
below. 

In order to use the patch facility, you must define your system with defsystem (see chapter 
28, page 660) and declare it as patchable widi the :patchabie option. When you load your 
system (with make-system, sec page 666), it is added to the list of all systems present in the 
world. The patch facility keeps track of which version of each patchable system is present and 
where the data about that system reside in the file system. This infonnation can be used to 
update the IJsp world automatically to die latest versions of all the systems it contains. Once a 
system is present, you can ask for the latest patches to be loaded, ask which patches are already 
loaded, and add new patches. 

You can also load in patches or whole new systems and then save the endre Lisp environment 
away in a disk parddon. This is explained on section 35.11, page 804. 
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When a l isp Machine is booted, it prints out a line of information for each patchabic system 
present in the booted l.isp world, saying which major and minor versions arc loaded. '11118 is 
done by print-herald (sec page 674). 

prlnt-system-modifIcatlons &rcst sysicin-names 

With no arguments, this lists all the systems present in this world and, for each system, 
all the patches that have been loaded into this world, bor each patch it shows the major 
version number (which is always the same since a world can only contain one major 
version), the minor version number, and an explanation of what die patch docs, as typed 
in by the person who made die patch. 

If print-system-modifications is called with arguments, only die modifications to the 
systems named arc listed. 

print-he raid &optional format-dest 

Prints the names and loaded version numbers of all patchabic systems loaded, and the 
microcode. Also printed arc the number of die band you booted, the amount of physical 
and virtual memory you have, die host name of the machine, and its associated machine 
name. Example: 

MIT System, band 7 of CADR-1. 

640K physical memory, 16127K virtual memory. 


System 

98.43 

CADR 

3.6 

ZMail 

53.10 

MIT-Specific 

22.0 

Microcode 

309 


MIT Lisp Machine One, with associated machine OZ. 
fonnai-dest defaults to t; if it is nil the answer is; returned as a string rather than printed 
out. format-dest cm also be a stream to print on. 

si: get-system-version &optional system 

Returns two values, the major and minor version numbers of the version of system 
currently loaded into the machine, or nil if that system is not present, system defaults to 
"System". 

si :system-vers1on-info &optional (brief-pwW) 

Returns a string giving information about which systems and what versions of the systems 
arc loaded into die machine, and what microcode version is running. A typical string for 
it to produce is: 

"System 98.48, CADR 3.6, MIT-Specific 22.0, microcode 309" 

If brief-p is t, it uses short names, suppresses die micrticodc version, any systems which 
should not appear in the disk label comment, the name System, and the commas: 

"98.48" 
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28.8.1 Defining a System 

In order to use the patch fiicility, you must declare your system as patchablc by giving tlic 
ipatchable option to defsystem (see chapter 28, page 660). The major version of your system in 
the file system is incremented whenever make-system is used to compile it. Thus a major 
version is associated with a set of OFASl. files. The major version of your system tliat is 
remembered as having been loaded into die Lisp environment is set to die major version in die 
file system whenever make-system is used to load your system and die major version in the file 
system is greater than what you had loaded before. 

After loading your system, you can save it with the disk-save function (sec page 807). disk- 
save asks you for any additional information you want printed as part of the greeting when the 
machine is booted. 'Phis is in addition to the names and versions of all the systems present in 
diis world. If the system version docs not fit in the partition comment field allocated in the disk 
label, disk-save asks you to type in an abbreviated form. 

28.8.2 Loading Patches 
load-patches &rcst options 

Phis function is used to bring the current world up to the latest minor version of 
whichever major veraon it is. for all systems present, or for certain specified systems. If 
there arc any patches available, load-patches offers to read tlicm in. With no 
arguments, load-patches updates all die systems present in this world. If you do not 
specify tlie systems to operate on, load-patches also reloads the site files if they have 
changed (section 35.12, page 810), and reloads the files defining logical host translations if 
they have changed (page 574). 

options is a list of keywords. Some keywords are followed by an argument. 'Phe 
following options arc accepted: 

:systems list list is a list of names of systems to be brought up to date. If this option 
is not specified, all patchable systems loaded are processed. 

runreleased Loads unreleased patches with no special querying. These patches should 
be loaded for experimental use if you wish the benefit of the latest bug 
fixes, but should not be loaded if you plan to save a band. 

:site Loads the latest site files if they have been changed since last loaded. 

This is the default if you do not specify explicitly which systems to 
process. 

rnosite Prevents loading of site files. This is the default when you specify the 

systems to process. 

:hosts Reloads the files defining logical host translations if they have been 

changed since last loaded. This is the default if you do not specify 
explicitly which systems to process. 

rnohosts Prevents loading of logical host translation files. This is tlie default when 
you specify the systems to process. 


PS;<L.MAN>PA1'CH.TKXT.54 


8-JUN-84 



676 


riic Piitch l-';icility 


I isp Miichine Maniuil 


:verbose Prims an explanation of what is being done. Tliis is tlic default. 

iselective For each patch, says what it is and Uicn ask tlic user whether or not to 

load it. This is tlic default. If the user answers P (for ‘Proceed’). 

<0 selective mode is turned off for any remaining patches to tlic current 

system. 

inoselective I'urns off :selective. 

:silent Turns off both :selective and -.verbose. In :silent mode all necessary 

patches arc loaded without printing anything and without querying the 
user. 

;force-unfinished 

Toads patches tJiat have not been finished yet, if they have been 
compiled. 

load-patches returns t if any patches were load<;d. 

When you load a patchablc system with make-system, load-patches is called automatically 
on that system. 

s1: patch-loaded-p maior^version minor-version &optional {sysiem-nome "SYSTEM") 

Returns t if the changes in patch inajorversion.minor-version of system system-name are 
loaded. If major-version is the major version of that system which is currently loaded, 
tlicn the changes in that patch arc loaded if the current minor version is greater than or 
equal to mi nor-version. If die currently loaded major version is greater than major-version 
tlicn it is assumed tliat tlie newer system version contains all die improvements patched 
into earlier versions, so the value is t. 

28.8.3 Making Patches 

There are two editor commands that are used to create patch files. During a typical 
maintenance session on a system you will make several edits to its source files. The patch system 
can be used tq copy these edits into a patch file so that they can be automatically incorporated 
into die system to create a new minor version. Edits in a patch file can be modified function 
definitions, new functions, modified defvar’s and defconst’s, or arbitrary forms to be evaluated, 
even including load’s of new files. 

The first step in making a patch is to start it. At this stage you must specify which patchable 
system you are making a patch for. Then you add one or more pieces of code from other source 
files to die patch. Finally you Jiiiish the patch. This is when you fill in the description of what 
the patch docs: this description is what load-patches prints when it offers to load the patch. If 
you have any doubts about whether the patch will load and work properly, you finish it 
unreleased', then you can load it to test it but no bands can be saved containing the patch until 
you explicitly release it later. 

It is important that any change you patch should go in a patch for die patchable system to 
which the changed source file belongs. 'ITiis makes sure that nobody loads the change into a Lisp 
world which docs not contain the file you were changing—rsomething that might cause trouble. 


PS:<L.MAN>PATCII.TEXT.54 


8-JUN'84 



I isp M;ichinc Maniuil 677 I'hc Patch l acility 

Also, it ensures Uiat you never patch changes to the same piece of code in tw'O diflerent patchable 
systems’ patches. I’his would lead to disaster because there is no constraint on the order in which 
patches to two dificrent systems are loaded. 

Starting a patch can be done with Meta-X Start Patch. It reads the name of die system to 
patch with the minibuffer. Meta-X Add Patch can also start a patch, so an explicit Meta-X 
Start Patch is needed only infrequently. 

Meta-X Add Patch adds the region (if there is one) or the current “defun" to the patch file 
currently being constructed. If you change a function, you should recompile it, test it, dien once 
it works use Add Patch to put it in the patch file. If no patch is being constructed, one is 
started for you: you must type in die name of die system to patch. 

A convenient way to add all your changes to a patch file is to use Meta-X Add Patch 
Changed Sections or Meta-X Add Patch Buffer Changed Sections, fhese commands ask you, 
for each changed function (or each changed function in the current buffer), whether to add it to 
the patch being constructed. If you use these commands more dian once, a function which has 
been added to die patch and has not been changed since is considered “unchanged”. 

Hie patch file being constmeted is in an ordinary editor buffer. If you mistakenly Add Patch 
something that doesn’t work, you can select die buffer containing die patch file and delete it. 
Then later you can Add Patch the corrected version. 

While you are making your patch file, the minor version number that has been allocated for 
you is reserved so that nobody else can use it. This way if two people arc patching a system at 
the same time, they do not both get die same minor version number. 

After testing and patching all of your changes, use Meta-X Finish Patch to install the patch 
file so that other users can load it. This compiles the patch file if you have not done so yourself 
(patches are always compiled). It also asks you for a comment describing the reason for the 
patch; load-patches and print-system-modifications print these comments. If the patch is 
complex or it has a good chance of causing new problems, you should not use Meta-X Finish 
Patch; instead, you should make an unreleased patch. 

A finished patch can be released or unreleased. If a patch is unreleased, it can be loaded in 
the usual manner if the user says ‘yes’ to a special query, but once it has been loaded the user 
will be strongly discouraged from saving a band. Therefore, you still have a chance to edit the 
patch file and recompile it if there is something wrong with it. You can be sure that the old 
broken patch will not remain pennanently in saved bands. 

To finish a patch without releasing it, use the command Meta-X Finish Patch Unreleased. 
Then the patch can be tested by loading it. After a sufficient period for testing, you can release 
the patch with Meta-X Release Patch. If you discover a bug in the patch after this point, it is 
not sufficient to correct it in this patch file; you must put the fix in a new patch to correct any 
bands already saved with the broken version of this patch. 

It is a good principle not to add any new features or fix any additional bugs in a patch once 
that patch is released: change it only to correct problems with tliat patch. New fixes to other 
bugs should go in new patches. 
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You can only be constriiclingOne patch at any time. Meta-X Add Patch automatically adds 
to the patch you arc constructing. Ilut you can start constructing a different patch without 
finishing the first. If you use the command Meta-X Start Patch while constructing a patch, you 
arc given the option of starting a new patch, fhe old patch ceases to be the one you arc 
constructing hut tlic patch file remains in its editor bufler. I.atcr, or in another session, you can 
go back to constructing the first patch with the command Meta-X Resume Patch. 'ITtis 
commands asks for both a patchablc system name and the patch version to resume constructing. 
You can simply save the editor buffer of a patch file and resume constructing tliat patch in a later 
session. You can even resume constructing a finished jjatch; though it rarely makes sense to do 
this unless the patch is unreleased. 

If you start to make a patch and change your mind, use the command Meta-X Cancel 
Patch. I'his deletes tlie record tliat says that this patch is being worked on. It also tells the 
editor that you are no longer constructing any patch. You can undo a finished (but unreleased) 
patch by using Resume Patch and tlien Cancel Patch. If a patch is released, you cannot 
remove it from saved bands, so it is not reasonable to cancel it at that stage. 

28.8.4 Private Patches 

A private patch is a file of changes which is not installed to be loaded automatically in 
sequence by all users. It is loaded only by explicit rcqiuest (using the function load). A private 
patch is not associated with any particular patchablc system, and has no version number. 

To make a private patch, use the editor command Meta-X Start Private Patch. Instead of a 
patchable system name, you must specify a filename to use for die patch file; since the patch is 
not to be installed, there is no standard naming convention for it to follow. Add text to the 
patch using Meta-X Add Patch and finish it using Meta-X Finish Patch, 'fherc is no concept 
of release for private patches so there is no point in using Meta-X Finish Patch Unreleased. 
There is also no data base recording all private patches, so Meta-X Start Private Patch will 
resume an existing patch, or even a finished patch. In fact, finishing a private patch is merely a 
way to write a comment into it and compile it. 

Once the private patch file is made, you can load it like any other file. 

The private patch facility is just an easy way to copy code from various files into one new file 
with Patch-File: T in its attribute list (to prevent warnings about redefining functions defined in 
other files) and compile tliat file. 
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28.8.5 System Status 

Tlic palch system has the concept i)f the stalus of a major version of a system. A status 
keyword is recorded in the l.isp world for each patchabic system tliat is loaded. I here is also a 
current status for each major version of each system, recorded in tlie patch directory file for tliat 
major version. Loading patches updates Hie status in the l.isp world to match tlic current status 
stored in die palch directory. The status in tlic patch directory is changed with si:set-system- 
status. 

The status is displayed when the system version is displayed, in places such as tlic system 
greeting message (print-herald) and the disk partition comment. 

The status is one of the following keywords: 

:experimental The system has been built but has not yet been fully debugged and released to 
users. Hiis is tlic default sUitus when a new major version is created, unless it is 
overridden with the linitial-status option to defsystem. 

;released ITic system is released for general use. 'Phis status produces no extra text in the 
system greeting and the disk partition comment. 

;obsolete ITie system is no longer supported. 

:broken This is like :experimental, but is used when the system was thought incorrectly to 
have been debugged, and hence was ireleased for a while. 

linconsistent Unreleased patches to this system have been loaded. If any patchabic system is in 
this status, disk-save demands extra confirmation, and the resulting saved band is 
identified as ‘‘Bad” in its disk partition comment. 

s1: set-system-status system status &optional major-version 

Changes the current status of a system, as recorded in the patch directory file, system is 
the name of the system, majorversion is the number of the major version to be changed; 
if unsupplied it defaults to the version currently loaded into the Lisp world, status should 
be one of the keywords above. 

Do not set the current system status to linconsistent. A status of :inconsistent is set up 
in the Lisp world when an unrelcased patch is loaded, and once set that way it never 
changes in that Lisp world. The status recorded in the system’s patch directory file should 
describe the situation where all currently released patches are loaded. It should never be 
:lnconsistent. 
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28.8.6 Patch Files 

The patch system maintains several different types of files in tlie directory asstKiated with your 
system. This directory is specified to defsystem via either tlie :patchable option or the 
:pathname-default option. 'ITvesc files are maintained automatically, but tlvey arc described here 
so that you can know what they arc and when they arc obsolete and can be deleted. 

If the :patchable option to defsystem had no argument, tlicn the patch data files arc stored 
on the host, device and directory specified as tlic system's ptithnamc dcfatilt. The names and 
types of tlic filenames arc all standard and do not includ(; the name of the system in any way. 

If tlvc ipatchable option to defsystem is given an argument, this argument is a file 
namestring specifying tlic host, device and directory to use for storing the patch data files. In 
addition, die system’s short name is used in constructing tlic names of tlic files. This allows you 
to store the patch data files for several systems in the same directory. 

1 ’herc arc three kinds of files that record patch infonnation; 

♦ the system patch directory 

ITiis file records tlie current major version number, so that when the system is recompiled a 
new number can be allocated. 

On Tops-20, tills file has, by default, a nafne like 0Z:PS:<MYD1R>PATCH.DIRECTORY, 
where the host, device, and directory (OZ:PS:<MYDIR>) come from tlic system’s :pathname- 
default as explained above. 

If :patchable is given an argument, this file. for system FOO has a name like 
OZ:PS:<PATDlR>FOO.PATCH-DlRECTORY, where the host, device and directory come from 
:patchable’s argument. 

* the patch directory of a major version 

I’hcre is a file of this kind for each major version of the system. It records the patches that 
have been made for that major version: the minor version, author, description and release 
status of each one. 

live daui in this file are in the form of a printed representation of a Lisp list with two 
elements. I'hc first is the system status of tliis major version (:experimental, ;released, 
:broken or :obsolete). The second is anotlicr list with an element for each patch. The 
element for a patch is a list of length four; the minor version, the patch description (a string) 
or nil for an unfinished patch, the author’s name (a string), and a flag that is t if tlie patoh is 
unreleased. 

On a Tops-20, for major version 259, this file has, by default, a name like 

0Z:PS;<MYDIR>PATCH-259.DIRECT0RY. 

If :patchable is given an argument, this file for system FOO has a name like 

OZ: PS:<PATDI R>FOO-259. PATCH - DIRECTORY. 
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* ihc individual patch 

l^'or each patch made, tlierc is a I.isp source file and a Qh'ASI. file. 

On a rops-20. for version 259.12, tlicse files have, by default, names like 

OZ:PS:<MYDIR>PATCH-259-12.LISP and OZ:PS;<MYDIR>PATCH-259-12.QFASL. 

If :patchable is given an argument, tliis file for system FOO has a name like 
OZ:PS:<PATDIR>FOO-259-12.PATCH-DIRECTORY. 

On certain types of file systems, slightly different naming conventions arc used to keep the 
names short enough to be legal. 
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29. Processes 

The I.isp Machine supports nwlii-processing\ several computations can be executed 
concurrently by placing each in a separate process. A process is like a processor, simulated by 
software. Hach prrx'ess has its own program counter, its own stitek of function calls and its own 
special-variable binding environment in which to execute its computation. (This is implemented 
with stack groups; see chapter 13, piigc 256.) 

If all tlie processes are simply tiding to compute, tht; machine allows them all to run an equal 
share of tlie time. This is not a particularly eOicient mode of operation since dividing tlie finite 
memory and prwessor power of the machine among sevtjral prtK'esses certainly cannot increase tlie 
available power and in fact wastes some of it in overhead. The typical use for piXK'esses is that at 
any time only one or two arc trying to run. I'he rest arc citJicr waHing for some event to occur 
or stopped and not allowed to compete for resources. 

A process waits for an event by means of the ptocess-wait primitive, which is given a 
predicate function which defines tlie event being waited for. A module of the system called the 
process scheduler periodically calls that function. If it returns nil tlie process continues to wait; if 
it returns t tlie prtKcss is made runnable and its call to process-wait returns, allowing the 
compuuition to prtKecd. 

A process may be active or stopped. Stopped processes are never allowed to run; they are 
not considered by the scheduler, and so can never become the current process until they are 
made active again. Ilie scheduler continually tests tlie waiting functions of all the active processes, 
and tliose which return non-nil values arc allowed to run. When you first create a process with 
make-process, it is inactive. 

The activity of a process is controlled by two sets of Lisp objects associated with it, called its 
run reasons and its arrest reasons. These sets are implemented as lists. Any kind of object can 
be in these sets; typically keyword symbols and active objects such as windows and other 
processes are found. A process is considered active when it has at least one nin reason and no 
arrest reasons. 

To get a computation to happen in another process, you must first create a process, then say 
what computation you want to happen in that process. Ihe computation to be executed by a 
process is specified as an initial function and a list of arguments to that function. When the 
process starts up it applies the ftinction to the arguments. In some cases the initial function is 
written so that it never returns, while in other cases it performs a certain computation and then 
returns, which stops tlie process. 

To reset a process means to exit its entire computation nonlocally using *unwind-stack (see 
page 82). Some processes are temporary and die when reset. Tlie other, permanent functions 
start their comptitations over again when reset. Resetting a process clears its waiting condition, so 
that if it is active it becomes runnable. 'I'o preset a function is to set up its initial ftinction (and 
arguments) and then reset it. This is how you start up a computation in a process. 
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All pruccsscs in a l isp Machine run in die same virtual address space, sharing the same set 
of Lisp objects. Unlike other systems tliat have special restricted mechanisms for inter-process 
communication, the I.isp Machine allows processes to communicate in arbitrary ways tlirough 
shared l.isp objects. One process can inform another of an event simply by changing the value of 
a global variable. Buffers containing messages from one process to another can be implemented as 
lists or arrays. I'he usual mechanisms of atomic operations, critical sections, and interlocks arc 
provided (sec store-conditional [page 688], without-interrupts (page 684], and process-lock 
[page 687]). 

A process is a l.isp object, an instance of one of several flavors of prcKCSs (see chapter 21, 
page 401). The remainder of this chapter describes tlic operations defined on processes, the 
functions you can apply to a process, and die functions and variables a program running in a 
process can use to manipulate its process. 


29.1 The Scheduler 

At any time there is a set of active processes’, as described above, these arc all die processes 
that arc not stopped. Rach active pnKCSS is cither currently running, runnable (ready to run), or 
waiting for some condition to become true. I'he active processes arc managed by a special stack 
group called the scheduler, which repeatedly examines each active process to determine whether it 
is waiting or ready to run. ITic scheduler then selects one process and starts it up. 

ITic process chosen by the scheduler becomes the current process, that is, the one process 
that is running on die machine, 'llic scheduler sets the variable current-process to it. It 
remains the current process and continues to run undl either it decides to wait, or a sequence 
break occurs. In cither case, the scheduler stack group is resumed. It then updates the process’s 
run time meters and chooses a new process to run next. This way, each process that is ready to 
run gets its share of time in which to execute. 

Each process has a priority which is a number. Most processes have priority zero. Larger 
numbers give a process more priority. The scheduler only considers the highest priority runnable 
processes, so if there is one runnable process with priority 20 then no process with lesser priority 
can run. 

The scheduler determines whether a process is runnable by applying the process’s wait-junction 
to its wait-argument-list. If the wait-function returns a non-nil value, then the process is ready to 
run; otherwise, it is waiting. 

A process can wait for some condition to become true by calling process-wait (see page 
685). Tills function sets the process’s wait-fimetion and wait-argument-list as specified by the 
caller, and resumes the scheduler stack group. A process can also wait for just a moment by 
calling process-allow-schedule (see page 686), which resumes the scheduler stack group but 
leaves the process runnable; it will run again as soon as all other runnable processes have had a 
chance. 

A sequence break is a kind of interrupt that is generated by the Lisp system for any of a 
variety of reasons; when it occurs, the scheduler is resumed. 'Flic function si:sb-on (see page 
687) can be used to control when sequence breaks occur. I’he default is to sequence break once a 
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second. I'hus even if a process never wails and is not stopped, it is forced to return control to 
die scheduler once a second so that any other runnable priKCSSCs can get their turn. 

The system docs not generate a sequence break when a page fault iKcurs; thus time spent 
waiting for a page to come in from the disk is “charged” to a process tlie same as time spent 
computing, and cannot be used by other priKesses. It is done this way for die sake of simplicity; 
this allows the whole implementation of the process system to reside in ordinary virtual memory, 
so diat it does not have to worry specially about paging. 'Lhe perfonnance penalty is small since 
Lisp Machines are personal computers, not multiplex<;d among a large number of proces.ses. 
Usually only one process at a time is runnable. 

A process’s wait function is free to touch any daia stnicturc it likes and to perform any 
computation it likes. Of course, wait functions should be kept simple, using only a small amount 
of time and touching only a small number of pages, or system performance will be impacted 
since the wait function will consume resources even when its process is not running. 

If a wait function gets an error, the error occurs inside the scheduler. If this enters the 
debugger, all scheduling comes to a halt until the user proceeds or aborts. Aborting in the 
debugger inside the scheduler “blasts” the current process by giving it a trivial wait fiinction that 
always returns nil; this prevents recurrence of die same jiroblem. It is best to write wait functions 
that cannot get errors, by keeping diem simple and by arranging for any problems to be detected 
before the scheduler sees the wait function, process-wait calls the wait function once before 
giving it to die scheduler, and this often exposes an error before it can interfere with scheduling. 

Note well that a process’s wait function is executed inside the scheduler stack-group, not 
inside die process. This means that a wait function may not access special variables bound in the 
process. It is allowed to access global variables. It can access variables bound by a process 
through die closure mechanism (chapter 12. page 250). If the wait function is defined lexically 
within the caller of process-wait dien it can access local variables dirough the lexical scoping 
mechanism. Most commonly any values needed by die wait function are passed to it as 
arguments. 

current-process Variable 

The value of current-process is the process that is currently executing, or nil while the 
scheduler is running. When the scheduler calls a process’s wait-function, it binds 
current-process to the process so that the wait-fjnetion can access its process. 

without-Interrupts body... Macro 

The body forms are evaluated with inhibit-scheduling-flag bound to t. This is the 
recommended way to lock out multi-processing over a small critical section of code to 
prevent Uming errors. In other words the body ii> an atomic operation. The values of the 
last form in the body are ultimately returned. 

In diis example, list is presumed to be a global variable referred to from two places in 
the code which different processes will execute. 
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(without-interrupts 
(push item list)) 

(without-interrupts 

(cond {(memq item list) 

(setq list (delq item list)) 
t) 

(t nil))) 

Inhibit-scheduling-fTag Variable 

i'he value of inhibit-scheduling-flag is normally nil. without-interrupts binds it to t, 
which prcvcnis prtK'css-swiiching until inhibit-scheduling-flag becomes nil again. It is 
cleaner to use without-interrupts than to refer directly to Uiis variable. 

process-wait wlwstaie funciion &rcst arguments 

This is the primitive for waiting. The current prtKCSS waits until tlie application of 
fiaiction to arguments returns non-nil (at which time process-wait returns). Note that 
function is applied in the environment of the scheduler, not the environment of the 
process-wait, so special bindings in effect when process-wait was called are not be in 
effect when function is applied. Be careful when using any free references in function, 
whostate is a string containing a brief description of the reason for waiting. If the who- 
line at the bottom of the screen is looking at this process, it will show whostate. 

Example; 

(process-wait "Buffer" 

^’(lambda (b) (not (zerop (buffer-n-things b)))) 
the-buffer) 

process-sleep interval 

Waits for interval sixtieths of a second, and then returns. It uses process-wait, 
sleep seconds 

Waits seconds seconds and then returns, seconds need not be an integer. This also uses 
process-wait. 

process-wa1t-w1th-t1meout whostate interval Junction &rest arguments 

lliis is like process-wait except that if interval sixtieths of a second go by and the 
application of Junction to arguments is still returning nil, then process-wait-with-timeout 
returns anyway. The value returned is the value of applying function to arguments’, thus, 
it is non-nil if the wait condition actually occurred, nil for a time-out. 

If interval is nil, there is no timeout, and this function is then equivalent to process- 
wait. 
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with-timeout {interval linicout-fonns...) body... Macro 

body is executed with a liineuut in efTcct for inlenal sixtieths of a second. If body finishes 
before that much time elapses, the values of the last form in body arc returned. 

If after inler\’al has elapsed body has not completed, its execution is terminated with a 
throw caught by the with-timeout form. ’ITien the timeout-forms arc evaluated and tlic 
values of the last one of them arc returned. 

For example, 

(with-timeout ((• 60. 60.) (format •query-io* " ... Yes.") t) 
(y-or-n-p "Really do it? (Yes after one minute) ")) 
is a convenient way to ask a question and assume an answer if the user docs not respond 
promptly. 'Ihis is a good thing to do for queries likely to occur when the user has 
walked away from the terminal and expects an operation to finish without his attention. 

process-allow-schedule 

Resumes the scheduler momentarily; all other processes will get a chance to run before 
tlic current prcKcss runs again. 

sysrscheduler-stack-group Constant 

'ITiis is the stack group in which the scheduler executes, 

sys :clock-function-l 1st • Variable 

1'his is a list of functions to be called by the scheduler 60 times a second. F,ach ftinction 
is passed one argument, the number of 60ths of a second since the last time that the 
functions on this list were called. I’hcsc functions implement various system overhead 
operations such as blinking the blinking cursor on the screen. Note that these fimetions 
are called inside the scheduler, just as arc tlie functions of simple processes (see page 
695). ITie scheduler calls these functions as often as possible, but never more often than 
60 times a second, lliat is. if there are no processes ready to run, the scheduler calls the 
clock functions 60 times a second, assuming tliat, all together,, they take less than 1/60 
second to run. If tliere are processes continuallj' ready to run, then the scheduler calls 
the clock functions as often as it can; usually iJiis is once a second, since usually the 
scheduler gets control only once a second. 

sys: active-processes Variable 

This is the scheduler s data-structure. It is a list of lists, where the car of each element is 
an active process or nil and tlie edr is information about that process. 

sys rail-processes Variable 

This is a list of all the processes in existence. It is mainly for debugging. 

si: Initial-process Constant 

This is the process in which the system starts up w'hen it is booted. 
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si:sb-on &opiic)nal when 

Controls what events cause'a sequence break, i.e. when rescheduling occurs. I he 
following keywords arc names of events which can cause a sequence break. 

:clock This event happens periodically based on a clock. 'ITic default period is 

one second. See sys:%tv-clock-rate, page 293. 

:keyboard Happens when a character is received from the keyboard. 

:chaos Happens when a packet is received from the Chaosnet, or transmission of 

a packet to the Chaosnet is completed. 

Since the keyboard and Chtiosnct are heavily buficred, tltere is no particular advantage to 
enabling tlic :keyboard and :chaos events, unless the :clock event is disabled. 

With no argument, si:sb-on returns a list of keywords for the currently enabled events. 

With an argument, the set of enabled events is changed. 'Htc argument can be a 
keyword, a list of keywords, nil (which disables sequence breaks entirely since it is the 
empty list), or a number, which is the internal mask, not documented here. 


29.2 Locks 

A lock is a software construct used for synchronization of two processes. A lock is either held 
by some process, or is free. When a process tries to seize a lock, it waits until the lock is free, 
and then it becomes the process holding the lock. When it is finished, it unlocks the lock, 
allowing some other prtKCSS to seize it. A lock protects some resource or data structure so that 
only one process at a time can use it. 

In the Lisp Machine, a lock is a locative pointer to a cell. If the lock is free, the cell 
contains nil; otherwise it contains the process that holds the lock. 'Hie process-lock and 
process-unlock functions arc written in such a way as to guarantee that two processes can never 
both think that tliey hold a certain lock; only one process can ever hold a lock at one time. 

process-lock locative &optional (/ocA:-vfl/MCcurrent-process) (u'/jos/a/e "Lock”) timeout 

This is used to seize the lock that locative points to. If necessary, process-lock waits 
until the lock becomes free. When process-lock returns, the lock has been seized, lock- 
value is the object to store into the cell specified by locative, and whostate is passed on to 
process-wait. 

If timeout is non-nil, it should be a fixnum representing a time interval in 60ths of a 
second. If it is necessary to wait more than that long, an error with condition name 
sysdock-timeout is signaled. 

process-unlock locative &optional (/oc^-va/uecurrent-process) 

This is used to unlock the lock that locative points to. If the lock is free or was locked 
by some other process, an error is signaled. Otherwise the lock is unlocked, lock-value 
must have the same value as the lock-value parameter to the matching call to process- 
lock, or else an error is signaled. 
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sys:lock-timeout (error) ^ Condition 

This condition is signaled when process-lock waits longer tJian tlie specified timeout. 

It is a good idea to use unwind-protect to make sure tliat you iinkKk any lock tltat you 
seize. For example, if you write 
(unwind-protect 

(progn (process-lock lock-3) 

(function-1) 

(function-2)) 

(process-unlock lock-3)) 

then even if function-1 or function-2 docs a throw, lock-3 will get unlocked correctly. 
Particular programs that use locks often define special forms tliat package tliis unwind-protect up 
into a convenient stylistic device. 

A higher level locking cotistmct is with-lock: 

with-lock {lock &kcy norecursive) body... Macro 

Executes die body with lock locked, lock should actually be an expression whose value 
would be tlie status of tlic lock; it is used inside locf to get a locative pointer with which 
the locking and unltKking are done. 

It is OK for one process to lock a lock multiple times, recursively, using with-lock, 
provided norecursive is not nil, 

norecursive should be literally t or nil; it is not evaluated. If it is t, this call to with- 
lock signals an error if the lock is already locked by the running process. 

A lower level construct which can be used to implement atomic operations, and is used in the 
implementation of process-lock, is store-conditional. 

store-conditional location oldvalue newvalue 

This stores newvalue into location iff location currently contains oldvalue. The value is t iff 
the cell was changed. 

If location is a list, tlic edr of the list is tested and stored in. This is in accord with the 
general principle of how to access the contents of a locative properly, and makes (store- 
conditional (locf (edr x)) ...) work. 

An even lower-level construct is the subprimitive %store-conditional, which is like store- 
conditional with no error checking, but is faster. 
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29.2.1 Process Queues 

A pnK'Css queue is a kind of lock which can record several processes which arc waiting for 
the lock and grant tlicin tlic lock in the order that they requested it. The queue has a fixed size. 
If the number of processes waiting remains less than tliat size tlien tliey will all get the lock in 
the order of requests. If too many pnxresses arc waiting tlicn the order of requesting is not 
remembered for tire extra ones, but proper interlocking is still mainutined. 

s1‘.make-process-queue name size 

Makes and returns a process queue object named name, able to record size processes. 
The count of size includes the process tliat owns tlic lock. 

s1: process-enqueue process-queue &op\\om\ lock-value who-staie 

Attempts to lock process-queue on behalf of lock-value. If lock-value is nil then tlic 
locking is done on behalf of current-process. 

If the queue is locked, then lock-value or the current process is put on tlic queue. Then 
this function waits for tliat lock value to reach tlic front of the queue. When it docs so, 
die lock has been granted, and the function returns. The lock is now locked in the name 
of lock-value or the current process, until si;process-dequeue is used to unlock it. 

who-sfale appears in the who line during the wait. It defaults to "Lock". 

s1 :process-deqau8ue process-queue &optional lock-value 

Unlocks process-queue, lock-value (which defaults to die current process) must be the 
value which now owns the lock on the queue, or an error occurs. The next process or 
odier object on the queue is granted the lock and its call to si:process-enqueue will 
therefore return. 

s1: reset-process-queue process-queue 

Unlocks the queue and clears out the list of things waiting to lock it 

si:process-queue-1ocker process-queue 

Returns the object in whose name the queue is currently locked, or nil if it is not now 
locked. 

29.3 Creating a Process 

There are two ways of creating a process. One is to create a permanent process which you 
will hold on to and manipulate as desired. ITie other way is to say simply, “call this function on 
these arguments in another process, and don’t bother waiting for the result.” In the latter case 
you never actually use the process itself as an object. 

make-process name &key ... 

Creates and returns a process named name. ITie process is not capable of running until it 
has been reset or preset in order to initialize the state of its computation. 
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Usually you do not need to specify any of die keyword arguments. The following I 

keyword arguments are allowed: • 

:simple-p Specifying t here gives you a simple process (see page 695). 

:flavor Specifies the flavor of process to be created. See section 29.5, page 695, 

for a list of all the flavors of process supplied by the system. 

:stack-group Specifics the stack group the jartKCSs is to use. If tliis option is not 
specified, a stack group is created according to die relevant options below. 

: warm - boot - action 

What to do with die process when the machine is booted. See page 693. 

:quantum See page 692. 

:priority See page 693. 

:run-reasons Lets you supply an initial nin reason. The default is nil. 

:arrest-reasons 

Lets you supply an initial arrest reason. The default is nil. 

:sg-area llie area in which to create the stack group. The default is the value of 
default-cons-area. 

:regular-pdl-area 

:special-pdl-area 

:regular-pdl-size 

:special-pdl-size 

These are passed on to make-sttick-group, page 259. 

:swap - sv - on-call - out 
:swap-sv-of-sg-that-calls-me 

:trap-enable Specify those attributes of the stack group. You don’t want to use these. 

If you specify :flavor, there can be additional options provided by that flavor. 

The following functions allow you to call a function and have its execution happen 
asynchronously in another process. This can be used either as a simple way to start up a process 
that will run “forever”, or as a way to make something happen without having to wait for it to 
complete. When the function returns, the process is returned to a pool of free processes for 
reuse. The only difference between these three functions is in what happens if the machine is 
booted while the process is still active. 

Normally the function to be run should not do any I/O to the terminal, as it docs not have 
a window and tcnninal I/O will cause it to make a notification and wait for user attention. Refer 
to section 13.5, page 264 for a discussion of the issues. 

ppocess-run-functlon name-or-optiom function &rest args 

Creates a process, presets it to apply function to args, and starts it running. The value 
returned is the new process. I’he process is killed if Junction returns; by default, it is 
also killed if it is reset. Example: 
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(defun background-print (file) 

(process-run-function "Print" 'hardcopy-file file)) 
creates a background process tliat prints tlte specified file. 

name-oj^options can be either a string specifying a name for tlie prcKCSs or a list of 
alternating keywords and values tliat can specify the name and various other parameters. 

:name This keyword should be followed by a string which specifies the name of 

the process. I'he default is "Anonymous". 

: restart-after-reset 

This keyword says what to do to die process if it is reset, nil means the 

process should be killed; anything else means the process should be 

restarted, nil is the default. 

: warm - boot - action 

What to do with die process when die machine is booted. See page 693. 
restart-after-boot 

This is a simpler way of saying what to do with die process when the 
machine is booted. If the :warm-boot-action keyword is not supplied or 
its value is nil, dien this keyword’s value is used instead, nil means the 

process should be killed; anything else means the process should be 

restarted, nil is the default. 

iquantum See page 692. 

:priority See page 693. 

process-run-rostaptable-functlon name-orkeywords function &rest args 

'ITiis is the same as process-run-function except that the default is that the process will 
be restarted if reset or after a warm boot. You can get the same effect by using 
process-run-function with appropriate keywords. 

29.4 Process Generic Operations 

These are the operations that are defined on all flavors of process. Certain process flavors may 
define additional operations. Not all possible operations are listed here, only those of interest to 
the user. 

29.4.1 Process Attributes 

:naroe Operation on sv.process 

Returns the name of the process, which was the first argument to make-process or 
process-run-function when the process was created. The name is a string that appears 
in the printed-representation of the process, stands for die process in the who-linc and the 
peek display, etc. 
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Operation on sv.process 


Returns the stack group currently executing on behalf of this pixKess. This can be 
different from the initial-stack-group if tlie process contains several stack groups tliat 
coroiitine among tliemsclves, or if the process is in tlic crror^handler, which runs in its 
own stock group. 

Note tliat the stock-group of a simple process (itee page 695) is not a stack group at all, 
but a function. 

: initial-Stack-group O/tm/z/on o//si: process 

Returns the suick group the initial-function is called in when the process starts up or is 
reset. 

: initial-form Operation on si.process 

Returns die initial “form” of the prcKess. This isn’t really a Lisp form; it is a cons 
whose car is the initial-fiinction and whose edr is tlie list of arguments to which that 
function is applied when the prcx:ess starts up or is reset. 

In a simple process (sec page 695), tlic initial form is a list of one clement, the process’s 
function. 

To change the initial form, use the :preset operation (see page 694). 

: wait-function Operation on sv.process 

Returns the process’s current wait-function, which is tlie predicate used by the scheduler 
to determine if tlic process is runnable. 'Phis is #’true if the process is running, and 
#’false if the process has no current computation (for instance, if it has just been 
credited, its initial function has returned) or if the program has decided to wait 
indefinitely. 'ITic wait-ftmetion of a flushed process is si:flushed-process, a function 
equivalent to # ’false but recognizably distinct. 

:wa1t-arguni0nt-l1st Operation o«si:process 

Returns the arguments to the process’s current wait-function. I’his is frequently the Srest 
argument to process-wait in the process’s stack. The system always uses it in a safe 
manner, i.c. it forgets about it before process-wait returns. 

: whostate Operation on si:process 

Returns a string that is the state of the process to go in the who-line at tlie bottom of the 
screen. Ihis is "run" if the process is running or trying to run; otherwise, it is the 
reason why the process is waiting. If the pnKCss is stopped, then this whostate string is 
ignored and the who-line displays arrest if the process is arrested or stop if the process 
has no run reasons. 

: quantum Operation on sv.process 

: set-quantum 60ths Operation on sv.process 

Respectively return and change the number of 60ths of a second this process is allowed to 
run without waiting before the scheduler will run someone else. The quantum defaults to 
1 second. 
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: quantum-remaining Opc/-<//;o;/o/i si:process 

Returns tlic amount of time remaining for tliis process Ui run, in 60tlis of a second. 

:pr1or1ty Operation on shprocess 

: set-priority priority-number Operation on s\:process 

Respectively return and change the priority of this process. The larger tlie number, the 
more this process gets to run. Within a priority level tlie scheduler runs all runnable 
processes in a round-robin fashion. Regardless of priority a process will not run for more 
tlian its quantum. The default priority is 0, and no normal process uses other than 0. 

: warm-boot-action Operation onsi;process 

: sot-warm-boot-action action Operation on sl.process 

Respectively return and change tlie process's warm-boot-action, which controls what 
happens if the machine is booted while this process is active. (Contrary to the name, Uiis 
applies to both cold and warm booting.) This can be nil or :flush, which means to flush 
tlie process (see page 695), or can be a function to call. 'ITie default is si:process- 
warm-boot-delayed-restart, which resets the prcKcss, causing it to start over at its 
initial function. You can also use si:process-warm-boot-reset, which tlirows out of the 
process’ computation and kills the prix:css, or si:process-warm-boot-restart, which is 
like tlie default but restarts the process at an earlier stage of system reinitialization. I'his 
is used for processes like the keyboard process and chaos background process, which are 
needed for reinitialization itself. 

:$1mp1e-p Operation on sv.process 

Returns nil for a normal process, t for a simple process. See page 695. 

:1dle-t1me Operation on sr.process 

Returns the time in seconds since this process last ran, or nil if it has never run. 

: total-run-time. Operation on sr.process 

Returns the amount of time this process has run, in 60ths of a second. This includes epu 
time and disk wait time. 

; dIsk-wal t-time Operation on si:process 

Returns the amount of time this process has spent waiting for disk I/O, in 60ths of a 
second. 

:cpu-t1me Operation on sr.process 

Returns the amount of time this process has spent actually executing instructions, in 60ths 
of a second. 

:percent-ut111zat1on Operation on sr.process 

Returns the fraction of the machine’s time this process has been using recently, as a 
percentage (a number between 0 and 100.0). Tlie value is a weighted average giving more 
weight to more recent history. 
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: reset-meters Opmiiion on sv.process 

Resets tlie run-time counters of the pnKess to zcip. 

29.4.2 Run and Arrest Reasons 

: run-reasons Operaiion on si.process 

Returns the list of run reasons, which arc tlic reasons why this process should be active 
(allowed to run). 

:run-reason object Opcraiionon si.process 

Adds objeci to the process’s run reasons, 'this can activate tlic prtKCSS. 

:revoke-run-roason object Operation on si.process 

Removes object from the process’s run reasons. 'Ibis can stop the prtKCSS. 

:arrest-reasons Operation on si:process 

Returns the list of arrest reasons, which are the reasons why this process should be 
inactive (forbidden to run), 

: arrest-reason object Operation on shprocess 

Adds object to the process’s arrest reasons. 'Ibis can stop the process. 

: revoke-arrest-reason object Operation on sUprocess 

Removes object from the process’s arrest reasons. 'Fhis can activate tlie process. 

:act1ve-p Operation on si:process 

:runnab1e-p Operation on sv.process 

These two operations are the same, t is returned if the process is active, i.e. it can run if 
its wait-function allows, nil is returned if the process is stopped. 

29.4.3 Bashing the Process 

; preset function &rest args Operation on sv.process 

Sets the process’s initial function to function and initial arguments to args. Ibc process is 
then reset so that any computation occuring in it is terminated and it begins anew by 
applying function to args. A :preset operation on a stopped process returns immediately, 
but docs not activate the process: hence the process will not really apply function to args 
until it is activated later. 

: reset &optional no-unwind kill Operation on sv.process 

Forces the process to throw out of its present computation and apply its initial function to 
its initial arguments, when it next runs. 'I'hc tlirowing out is skipped if the process has 
no present computation (c.g. it was just created), or if the no-unwind option so specifies. 
The possible values for no-unwind are: 

:unless-current 

nil Unwind unless the stack group to be unwound is the one currently 

executing, or belongs to the current process. 
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;always Unwind in all cases. This may cause Ihc operation to throw through its 

caller instead of returning. 

t Never unwind. 

If kill is t, the process is to be killed after unwinding it. This is for internal use by the 
:kill operation only. 

A .'reset operation on a stopped process returns immediately, but docs not activate the 
process; hence the prrKCSs will not rctilly get reset until it is ticlivatcd later. 

: f 1 ush Opcniiioii on si:process 

Forces the process to wait forever. A prcKCSs may not :flush itself. Flushing a process is 
difl'erent from stopping it, in that it is still active and hence if it is reset or preset it will 
suirt running again. 

A flushed prtKCSS can be recognized because its wait-function is sidlushed-process. If a 
prtKCSS belonging to a window is flushed, exposing or selecting the window resets the 
process. 

:kin Operation on sv.process 

Gets rid of the process. It is reset, stopped, and removed from sysrall-processes. 

: Interrupt Junction &rcst args " Operation onsv.process 

Forces the process to apply function to args. When function returns, the process 
continues the intcrniptcd computation. If the process is wailing, it wakes up, calls 
Junction, then waits again when Junction returns. 

If the process is stopped it docs not apply function to args immediately, but will later 
when it is activated. Nonnally the :interrupt operation returns immediately, but if the 
process's stack group is in an unusual internal stale linterrupt may have to wait for it to 
get out of that state. 

29.5 Process Flavors 

These are the flavors of process provided by the system. It is possible for users to define 
additional flavors of their own. 

s1: process Flavor 

This is the standard default kind of process. 

s1: simple-process Flavor 

A simple process is not a process in the conventional sense. It has no stack group of its 
own; instead of having a stack group that gets resumed when it is time for the process to 
run, it has a function tliat gets called when it is time for the process to run. When the 
wait-function of a simple process becomes true, and the scheduler notices it, the simple 
process’s function is called in the scheduler’s own slack group. Since a simple process 
does not have any stack group of its own, it can’t save control state in between calls; any 
state that it saves must be saved in data structure. 
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The only advantage of simple processes over normal processes is that they use up less 
system overhead, since they can be scheduled without the cost of resuming stack-groups. 
They arc intended as a special, efficient mechanism for certain purposes. For example, 
packets received from the Chaosnet arc examined and distributed to the proper receiver by 
a simple prrx'ess tliat wakes up whenever there arc any packets in tlie input buffer. 
However, they are harder to use, because you can’t save state information across 
scheduling. That is, when the simple process is ready to wait again, it must return; it 
can't call process-wait and continue to do something else later. In fact, it is an error to 
call process-wait from inside a simple process. Another drawback to simple pr(x:esses is 
that if tlic function signals an error, the scheduler itself is broken and multiprwessing 
stops; this situation can be repaired only by aborting, which blasts the prrKCSS. Also, 
when a simple process is run, no cither prcKCSS is scheduled until it chooses to return; so 
simple processes should never run for a long time without returning. 

Asking for the stack group of a simple prcKess does not signal an error, but returns the 
prcKcss's function instead. 

Since a simple process cannot call process-wait, it needs some other way to specify its 
wait-fimction. To set the wait-function of a simple process, use si:set-process-wait (see 
below). So, when a simple prcKess wants to wait for a condition, it should call si:set- 
process-wait to specify the condition, then return. 

si:set-process-wait simple-process wail-function mit-argument-list 

Sets the wail-function and wail-argument-list of simple-process. Sec the description of the 
si;simple-process flavor (above) for more information. 

29.6 Other Process Functions 

process-enable process 

Activates process by revoking all its run and arrest reasons, then giving it a run reason of 
:enable. 

process-reset-and-onable process 
Resets process, then enables it. 

process-disable process 

Stops process by revoking all its run reasons. Also revokes all its arrest reasons. 

d’hc remaining functions in this section are obsolete, since they simply duplicate what can be done 
by sending a message. ITicy arc documented here because their names are in the global package. 

process-preset process function &rcst args 
Sends a :preset message. 
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process-reset process 

Sends a :reset mcssiigc. 

process-name process 

Gets the name of a process, like Utc :name operation, 
process-stack-grotipt process 

Gels the ciirrcnl stack group of a priKCSS, like tlic :stack-group operation. 

process-in1t1al-stack-group process 

Gets the initial stack group of a process, like the :initial-stack-group operation, 

process-1nit1al-form process 

Gets the initial form of a prtx'ess, like the :initial-form operation. 

process-wait-function process 

Gets the current wait-function of a process, like tlte :wait-function operation. 

process-wait-argument-list p 

Gets the arguments to tlic current wait-function of a process, like the :wait-argument-list 
operation. 

process-whostate p 

Gets the current who-line state string of a process, like the :whostate operation. 
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30. Errors and Debuggings 

The first portion of this chapter explains how programs can handle errors, by means of 
condition handlers. It alst) explains how a program can signal an error if it detects something it 
doesn’t like. 

The second explains how users can handle errors, by means of an interactive debugger; that 
is, it explains how to recover if you do something wrong. A new user of tlie 1-isp Machine, or 
someone who just wants to know how to deal witli errors and not how to cause tliem, should 
ignore the first sections and skip ahead to section 30.7, page 726, 

I’lic remaining sections describe some other debugging facilities. Anyone who is going to be 
writing programs for die Tisp Machine should familiarize himself with these. 

The trace facility provides the ability to perform certain actions at the time a function is 
called or at die time it returns. 'I’he actions may be simple typeout, or more sophisticated 
debuggini? functions. 

The advise facility is a somewhat similar facility for modifying the behavior of a function. 

The breakon facility allows you to cause the debugger to be entered when a certain function is 
called. You can then use the debugger’s stepping commands to step to the next function call or 
return. 

The step facility allows the evaluation of a form to be intercepted at every step so that the 
user may examine just what is happening throughout the execution of the fonn. Stepping works 
only on interpreted code. 

'I’he MAR facility provides the ability to cause a trap on any memory reference to a word (or 
a set of words) in memory. If something is getting clobbered by agents unknown, this can help 
track down the source of the clobberage. 

30.1 Conditions 

Programmers often want to control what action is taken by their programs when errors or 
other exceptional situations occur. Usually different situations are handled in different ways, and 
in order to express what kind of handling each situation should have, each situation must have an 
associated name. In Zetalisp, noteworthy events are represented by objects called condition 
instances. When an event occurs, a condition instance is created; it is then signaled, and a 
handler for that condition may be invoked. 

When a condition is signaled, the system (essentially) searches up the stack of nested function 
invocations looking for a handler established to handle that condition. ITic handler is a function 
that gets called to deal with the condition. The condition mechanism itself is just a convenient 
way for finding an appropriate handler function for a particular exceptional situation. 
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When a condition is signaled, 7i comlilion instance is created to represent die event iind hold 
information about it. This information incltides condition names llien classify the condition and 
any other data that is likely to be of interest to condition handlers. A condition insUincc is 
immutable once it has been created. Some conditions arc errors, which means tliat the debugger 
is invoked if tlicy arc signaled and not handled. 

Condition instances are flavor instances. The flavor condition is the base flavor from which 
all fltivors of condition arc built. Several operations that arc defined on condition insUinccs arc 
described below, 'live flavor error, which is built on condition, is the base flavor for all kinds of 
conditions which are errors. 

A condition name is a symbol then is used to identify a category of conditions, l^ach 
condition insuince possesses One or more condition names. Kttch condition handler specifics one or 
more condition names that it should apply to. A handler applies to a condition if tlicy have any 
condition names in common. This is the sole purpose of condition names: to match condition 
institnccs with dicir handlers. 'I'hc meaning of every condition name signaled by die system is 
described in this manual. Ilie condition name index is a directory for diem. Conditions that are 
errors possess the condition name error. 

In PL/1, CLU, ADA and most other systems that provide named conditions, each condidon 
has only one name. 'I'hat is to say, the categories identified by condition names are disjoint. In 
Zctalisp. each condition instance can have multiple condition names, which means that the 
categories identified by condition names can overlap and be subdivided. 

For example, among the condidon names defined by the system are condition, error, 
sys:arithmetic-error, sys:floating-exponent-underflow and sys:divide-by-zero. condition is a 
condition name that all condition instances possess, error idendfies the category of conditions that 
are considered errors. sys:arithmetic-error idendfies the category of errors that pertain to 
arithmetic operations. sys:floating-exponent-underflow and sys;divide-by-zero arc the most 
specific level of categorization. So, the condition signaled when you evaluate (* 1s-30 1s-30 
1s-30 1S-30) possesses condition names sys:floating-exponent-underflow, sysrarithmetic-error, 
error and condition, while the one signaled if you evaluate (// 1 0) possesses condition names 
sys:divide-by-zero, sys:arithmetic-error, error and condition. In this example, the categories 
fall into a strict hierarchy, but this docs not need to be the case. 

Condition names are documented throughout the manual, with definitions like this: 

sys;d1v1d0-by-Z0ro (sys:arithmetic-error error) Condition 

The condition name sys:divide-by-zero is always accompanied by sys:arithmetic-error 
and error (that is, it categorizes a subset of those categories). The presence of error 
implies that all sys:divide-by-zero condidons are errors. 

The condition instance also records additional information about the event. For example, the 
condition instance signaled by dividing by zero handles tlie :function operation by returning the 
function that did the division (it might be truncate, floor, ceiling or round, as well as //). In 
general, for each condition name there arc conventions saying what additional information is 
provided and what operations to use to obtain it. 
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I’lic flavor of the condition instance is always one of the condition names, and so arc its 
component flavors (with a few exceptions; si.vanilla-flavor and some other flavor components arc 
omitted, since they arc not useful categories for condition handlers to specify). In our example, 
the flavor of the condition is sys:arithmetic-error, and its components include error and 
condition. Condition names require new flavors only when they require significantly different 
handling by the error system; you will understand in derail after finishing tliis section. 

Cond1t1on-typep condilion-itisfance amiition-naine 

Returns t if condilion-insiancc possesses condition name amdiHou-name. condUioii-name 
can also be a combination of condition names using and, or and not; then die condition 
tested for is a biMilcan combination of the presence or absence of various condition names, 
Hxamplc: 

(condition-typep error ’fs:fi1e-not-found) 

(condition-typep error 

’(or fs:fi1e-not-found fs:directory-not-found)) 

errorp object 

Returns t if object is a condition instance and its flavor incorporates error, 'fhis is 
normally equivalent to (typep object ’error). Some functions such as open optionally 
return the condition instance rather than signaling it, if an error occurs, errorp is useful 
in testing the value returned. 

:cond1t1on-names • Operation on condlWon 

Returns a list of all the condition names possesses by this condition instance. 

30.2 Handling Conditions 

A condition handler is a function that is associated w'ith certain condition names (categories of 
conditions). The variable ehxondition-handlers contains a list of the handlers that are current; 
handlers are established using macros which bind this variable. When a condition is signaled, this 
list is scanned and all the handlers which apply are called, one by one, until one of the handlers 
eitlier throws or returns non-nil. 

Since each new handler is pushed onto the front of eh:condition-handlers, the innermost- 
established handler gets the first chance to handle the condition. When the handler is run, 
ehxondition-handlers is bound so that the running handler (and all the ones that were 
established farther in) are not in effect. This avoids the danger of infinite recursion due to an 
error in a handler invoking the same handler. 

One thing a handler can do is throw to a tag. Often the catch for this tag is right next to 
the place where the handler is established, but this does not have to be so. A simple handler 
that applies to all errors and just tlirows to a tag is established using ignore-errors. 

ignope-errors body... Macro 

An error within the execution of body causes control to return from the ignore-errors 
form. In this case, the values arc nil, t. If there is no error inside body, the first value 
is that of the last form in the body and the second is nil. 
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l-’rrors whose condition instances return true for the :dangerous-condition-p operation 
arc not handled. I'hcsc include such tilings as running out of virtual memory. 

A handler can also signal another condition. For example, signaling sysrabort has tlic effect 
of pretending tliat tlic user typed the Abort key. 'Hie following function creates a handler which 
signals sysrabort. 

s1:eval-abort-tr1v1al-errors form 

F'valuaies form with a condition handler for many common error conditions such as 
rwrong-type "argument, runbound-variable and runclaimed-message. I'he handler 
asks tlic user wliether to allow the debugger to be entered. If die user says ‘no', die 
handler signals the sysrabort condition. If die user says ‘yes', die handler docs not 
handle the condition, allowing the debugger to do so. 

In some eases the handler attempts to determine whether die incorrect variable, operation, 
or argument appeared in form: if it did not, the debugger is always allowed to run. The 
assumption is that form was typed in by the user, and die intention is to distinguish 
trivial mistakes from program bugs. 

'I'he handler can also ask to pnxreed from the condition. 'I’his is done by returning a non-nil 
value. Sec the section on proceeding, page 717, for more information. 

'The handler can also decline to handle the condition, by returning nil. Then the next 
applicable handler is called, and so on until either some handler does handle the condition or 
there arc no more handlers. 

'The handler function is called in the environment where the condition was signaled, and in 
the same stack group. All special variables have the values they had at the place where the 
signaling was done, and all catch tags that were available at the point of signaling may be thrown 
to. 


'Fhe handler receives the condition instance as its first argument. When establishing the 
handler, you can also provide additional arguments to pass to the handler when it is called. 'This 
allows the same function to be used in varying circumstances. 

The fundamental means of establishing a condition handler is the macro condition-bind. 

cond1t1on-b1nd {handlers...) body... Macro 

cond1t1on-b1nd-defau1t (handlers...) body... Macro 

A condition-bind form looks like this: 

(condition-bind {{conditions handler-form additional-arg-forms...) 

{conditions handler-form additional-arg-forms...)) 

body...) 

The purpose is to execute body with one or more condition handlers established. 

Each list of conditions and handler-form establishes one handler, conditions is a condition 
name or a list of condition names to which the handler should apply. It is not evaluated. 
handler-form is evaluated to produce the function that is the actual handler. The 
additional-arg-forms are evaluated, on entry to the condition-bind, to produce additional 
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argunicnls that arc passed to tlic handler functicin when it is called. I'he arguinents to tlic 
handler function arc the condition instance being signaled, followed by the values of any 
addiihuml-argrforms. 

conditions can be nil; then the handler applies to all conditions that arc signaled. In this 
case it is up to tlic handler function to decide whether to do anything. It is important for 
tlic handler to refrain from handling certain conditions that arc used for debugging, such 
as break and eh:call-trap. The idebugging-condition-p operation on condition 
instances returns non-nil for these conditions. Certain other conditions such as 
sys;virtual-memory-overflow should be handled only with great care. The ;dangerous- 
condition-p operation returns non-nil for Uicsc conditions. Hxamplc: 

(condition-bind {(nil 'myhandler "it happened here" 45)) 

{catch ’ X 

...)) 

(defun myhandler (condition string value) 

(unless (or {conditton-typep condition ’fs:fi1e-error) 

(send condition :dangerous-condition-p) 

(send condition :debugging-condition-p)) 

(format error-output string condition) 

(throw ’x value))) 

myhandler declines to handle file errors, and all debugging conditions and dangerous 
errors. For all other conditions, it prints the string specified in the condition bind and 
throws to die tag x the value specified there (45). 

condition-bind-default is like condition-bind but establishes a default handler instead of 
an ordinary handler. Default handlers work like ordinary handlers, but they are tried in a 
different order: first all the applicable ordinary handlers are given a chance to handle the 
condition, and then the default handlers get theur chance. A more flexible way of doing 
tilings like this is described under signal-condition (page 715). 

Condition handlers that simply throw to the function that established them are very common, 
so there arc special constructs provided for defining them. 

condition-case {variables...) body'-form clauses... Macro 

(condition-case {variable) 
body-form 

{condition-names forms...) 

{condition-names forms...) 

...) 

body-form is executed with a condition handler established that will throw back to the 
condition-case if any of the specified condition names is signaled. 

F.ach list starting with some condition names is a clause, and specifies what to do if one 
of those condition names is signaled, condition-names is either a condition name or a list 
of condition names; it is not evaluated. 
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Once Lite handler per se htis done the throw, Lite clauses arc tested in order until one is 
found thill itpplics. This is almost like a selectq, except that the signaled condition can 
have several condition names, so the first cliiusc ihiit matches any of them gets to run. 
The forms in the clause arc executed with variable bound to the condition instance that 
was signaled, fhe values of the litsi form in tlic clause iirc returned from the condition- 
case form. 

If none of the specified conditions is signaled during the execution of body-farm (or if 
other handlers, csttiblishcd within body-form, handle them) then the values of body-form 
are returned from the condition-case form. 

variable may be omitted if it is not used. 

It is also possible to have a clause starling with :no-error in place of a condition name. 
This clause is executed if body-form finishes normally. Instead of just one variable tltcre 
can be several variables; during the execution of the :no-error clause, tltcsc arc bound to 
the values returned by body-form. Ilic values of the last fonn in the clause become the 
values of the condition-case form. 

Here is an example: 

(condition-case () 

(print foo) 

(error (format t " «Error in printing»"))) 

condition-call {variables...) body-form clauses... Macro 

condition-call is an extension of condition-case that allows you to give each clause an 
arbitrary conditional expression instead of just a list of condition names. It looks like this: 
(condition-call {variables...) 
body-form 
{test forms...) 

{test forms...) 

...) 

The difference between this and condition-case is the test in each clause. The clauses in 
a condition-call resemble the clauses of a cond rather than those of a selectq. 

When a condition is signaled, each test is executed while still within the environment of 
the signaling (that is, within the actual handler function). The condition instance can be 
found in the first variable. If any test returns non-nil, then the handler throws to the 
condition-call and the corresponding clause’s forms are executed. If every lest returns nil, 
the condition is not handled by this handler. 

In fact, each test is computed a second time after the throw has occurred in order to 
decide which clause to execute. I’he code for the test is copied in two different places, 
once into the handler function to decide whether to throw, and once in a cond which 
follows tlie catch. 

The last clause can be a :no-error clause just as in condition-case. It is executed if the 
body returns without error. The values returned by tlie body are stored in the variables. 
ITic values of the last form in the :no-error clause are returned by the condition-call. 
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Only Uic first of variables is used if llicrc is no :no-error clause, flic variables may be 
omitted entirely in the unlikely event that none is used. Kxample: 

(condition-call (instance) 

(do-it) 

((condition-typep instance 

’(and fs:fi1 e-error (not fs:no-more-room))) 

(compute-what-to-return))) 

The condition name fs:no-more-room is a subcategory of fs:file-error; Uiercfore, this 
handles all file errors rjrcrp/for fs;no-more-room. 


1-uich of the four condition handler esuiblishing constructs has a conditional version tliat 
decides at run time whether to establish the handlers. 

cond1t1on-b1nd-1f comi-fonn (handlers...) body... Macro 

(condition-bind-if cond-fonn 

((conditions handler-form additional-arg-fonns ...) 
{conditions handler-form additional-arg-forms ...)) 

body ...) 

begins by executing cond-fonn. If it returns non-nil, tlicn all proceeds as for a regular 
condition-bind. If cond-form returns nil, then the body is still executed but without the 
condition handler. 

condit1on-case-1f cond-form (variables.,.) body-form clauses... Macro 

(condition-case-if cond-form (variables...) 
body-form 

(condition-names forms...) 

(condition-names fonns...) 

begins by executing cond-form. If it returns non-nil, then all proceeds as for a regular 
condition-case. If cond-form returns nil, then the body-form is still executed but without 
tlic condition handler, body-form's values are rc;turncd, or, if there is a :no-error clause, 
it is executed and its values returned. 


condition-call-if cond-form ([variable]) body-form clauses... Macro 

(condition-call-if cond-form (variables...) 
body-form 
(test forms...) 

(test forms...) 

...) 

begins by executing cond-form. If it returns non-nil, tlicn everything proceeds as for a 
regular condition-call. If cond-form returns nil, then the body-form is still executed but 
without the condition handler. In that case, body-form's values are returned, or, if there 
is a :no-error clause, it is executed and its values returned. 
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COnd1t1on-b1nd-default-if coud-jhnn (handlers...) body... I^ltnro 

Ihis is used just like condition-bind-if, btit establishes a default handler instead of an 

ordinary handler. 

eh: condition-handlers Variable 

This is the list of established condition handlers. Btch clement looks like tliis: 

(condilion-naines function addilional-arg-valucs.. .) 
condilion-naincs is a condition name or a list of condition names, or nil which means all 
conditions. 


function is tltc actual handler function. 

additional-arg-valucs arc additional arguments to be passed to tlic function when it is 
called, function'?, first argument is always the condition instance. 

Both die links of the value of ehxondition-handlers and the elements arc usually created 
with with-stack-list, so copy tlicm if you want to save tlicm for any period of time. 

eh: condltlon-default-handlers Variable 

1'his is the list of csuiblishcd default condition handlers. 'I'hc data format is the same as 
that of ehxondition-handlers. 


30.3 Standard Condition Flavors 


condition 

The flavor condition is the base flavor of all conditions, 
for all the operations described in this chapter. 


Flavor 

and provides default definitions 


condition incorporates si;property-list-mixin, which defines operations :get and .plist. 
Each property name on the property list is also an operation name, so tliat sending the 
:foo message is equivalent to (send instance :get :foo). In addition, (send instance :set 
:foo value) is equivalent to (send instance ;set :get :foo value). 

condition also provides two instance variables, eh;format-string and eh:format-args. 
condition’s method for the the :report operation passes these to format to print the error 
message. 


error 


Flavor 

The flavor error makes a condition an error condition, errorp returns t for such 
conditions, and the debugger is entered if they are signaled and not otherwise handled. 


sys:no-act1on-ffl1x1n 

This mixin provides a definition of the proceed type :no-action. 


Flavor 
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sys :proceed-w1th-value-fn1x1n Flavor 

This inixin provides a definition of the prtKCcd type :new-value. 

f error llavor 

This flavor is a mixture of error, sys:no-action-mixin and sys:proceed-with-value- 
mixin. It is the flavor used by default by the functions terror and cerror, and is often 
convenient for users to instantiate. 

sys: warning Flavor 

This flavor is a mixture of sys:no-action-mixin and condition. 

sys:bad-array-m1x1n Flavor 

This mixin provides a definition of the prcKeed type :new-array. 


30.4 Condition Operations 

F.very condition instance can be asked to print an error message which describes the 
circumstances tliat led to the signaling of tlie condition. I'he easiest way to print one is to print 
the condition instance without escaping (princ, or format operation ~A). This actually uses the 
:report operation, which implements the printing of an error message. When a condition instance 
is printed with escaping, it uses the #c syntax so that it can be read back in. This is done 
using si;print-readably-mixin. page 446. 

: report stream Operation on condition 

Prints on stream the condition’s error message, a description of the circumstances for 
which the condition instance was signaled. 'I’he output should neither start nor end with a 
carriage return. 

If you are defining a new flavor of condition and wish to change the way the error 
message is printed, this is the operation to redefine. All others use this one. 

: report-string Operation on condition 

Returns a string containing the text that the :report operation would print 

Operations provided specifically for condition handlers to use: 

:dangerous-cond1t1on-p Operation on condition 

Returns t if die condition instance is one of diose that indicate events that arc considered 
extremely dangerous, such as ninning out of memory. Handlers that normally handle all 
conditions might want to make an exception for tliese. 

:debugg1ng-cond1t1on-p Opero/Zon on condition 

Returns t if the condition instance is one of those that are signaled as part of debugging, 
such as break, which is signaled when you type Meta-Break. Although these conditions 
noimally enter the debugger, they are not errors; this serves to prevent most condition 
handlers from handling them. But any condition handler which is written to handle all 
conditions should probably make a specific exception for these. 
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See also the operaiiiais :proceed-types and proceed-type-p, which liavc to do with 
proceeding (page 717). 

30.4.1 Condition Operations for the Debugger 

Some operations are intended for the debugger to use. I'licy are documented because some 
flavors of condition redefine them so as to cause the debugger to behave diflcrcntly. Ibis section 
is of interest only to advanced users. 

: print-error-message stack-group bhef-flag stream Operation oncondHion 

This operation is used by the debugger to print a complete error message. This is done 
primarily using the :report operation. 

Certain flavors of condition define a :after print-error-message method which, when 
brief-flag is nil, prints additional helpful information which is not part of the error 
message per sc. Often this requires access to the stack group in addition to tlic data in 
tlic condition instance/ fhe method can assume that if brief-flag is nil tlicn stack-group is 
not the one which is executing. 

For example, the print-error-message metliod of the condition signaled when you call 
an undefined ftmetion checks for the case of calling a function such as bind that is 
meaningful only in compiled code; if that is what happened, it searches the stack to look 
for the name of the ftmetion in which the call appears. This is information that is not 
considered crucial to the error itself, and is therefore not recorded in the condition 
instance. 

tmaybe-cTeap-Input stream Operation on condition 

This operation is used on entry to the debugger to discard input. Certain condition 
flavors, used by stepping redefine this operation to do nothing, so that input is not 
discarded. 

:bug-report-rec1pient-system Operation on condition 

The value returned by this operation is used to determine what address to mail bug 
reports to, when the debugger Control -M command is used. By default, it returns 
"LISPM". The value is passed to.tlie function bug. 

:bug-report-descr1ption stream &optional numeric-arg Operation on condition 

This operation is used by die Control -M command to print on stream the information 
that ^ould go in the bug report, numeric-arg is the numeric argument, if any, that the 
user gave to the Control -M command. 

:f 1nd-current-frame stack-group Operation on condition 

Returns the stack indices of the stack frames that the debugger should operate on. 

ITie first value is the frame “at which the error occurred.” This is not the innermost stack 
frame; it is outside the calls to such functions as Terror and signal-condition which were 
used to signal the error. 
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The second value is llic initial value for the debugger command loop’s current frame. 

The tliird value is the innermost frame tliat the debugger should be willing to let die user 
see. By default this is the innermost active frame, but it is safe to use an open but not 
active frame within it. 

The fourth value, if non-nit, tells die debugger to consider die innermost frame to be 
“interesting”. Normally, frames that arc part of the interpreter (calls to si:eval1, 
si:apply-lambda, prog, cond, etc.) arc considered uninteresting. 

This is a flavor operation so that certain flavors of condition can redefine it. 

: debugger-command-loop O/Jcra/w //oh condition 

stack-group «S:optional error-object 

Enters die debugger command loop. The initial error message and backtrace have already 
been printed. This message is sent in an error handler stack group; stack-group is the 
stack group in which the condition was signaled, error-object is the condition object which 
was signaled; it defaults to the one the message is sent to. 

This operation uses :or mcdiod combination (see section 21.11, page 433). Some 
condition flavors add methods that perform some other sort of processing or enter a 
different command loop. For example, unbound variable errors look for look-alike 
symbols in other packages at this point. If the added mcdiod returns nil, the original 
method that enters the usual debugger command loop is called. 

30.5 Signaling Conditions 

Signaling a condition has two steps, creating a condition instance and signaling the instance. 
There are convenience interface fitnetions that combine the two steps. You can also do them 
separately. If you just want to signal an error and do not want to worry much about condition 
handling, the function (error is all you need to know. 

30.5.1 Convenience Functions for Signaling 

ferror &rest make-condition-arguments 

Creates a condition instance using make-condition and then signals it with signal- 
condition, specifying no local proceed types, and with t as the use-debugger argument so 
the debugger is always entered if the condition is not otherwise handled. 

'I'hc first argument to (error is always a signal name (often nil). Hie second argument is 
usually a format string and the remaining arguments are additional arguments for format; 
but this is under die control of the definition of the signal name. Example: 

(ferror ’math:singular-matrix 

"The matrix ~S cannot be inverted." matrix) 

For compatibility with the Symbolics system, if the first argument to ferror is a string, 
then a signal name of nil is assumed. The arguments to ferror are passed on to make- 
condition with an additional nil preceding them. 
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If yon prefer, you can use the formatted output functions (page 496) to generate Uic error 
message. Here is an example, though in a simple case like this using format is easier: 
(ferror ’math:singular-matrix 
{format:outfmt 
"The matrix " 

(pninl matrix) 

" cannot be inverted,") 
number) 

In this Ciise, arguments past the second one arc not used for printing the error message, 
but the signal name may still expect them to be present so it can put tlicm in the 
condition instttncc. 

cerrop pwcecJ-lype ignore signal-name SltcsI signal-name-arguments 

Creates a condition instance, by passing the signal-name and signal-name-arguments to 
make-condition, and tlicn signals it. If proceed-type is non-nil then it is provided to 
signal-condition as a proceed type. For compatibility with old uses of cerror, if 
proceed-type is t. :new-value is provided as the prtrcccd type. If proceed-type is :yes, 
:no-action is provided as the proceed type. 

The second argument to cerror is not used and is present for historical compatibility. It 
may be given a new meaning in the future. 

If a condition handler or tltc debugger decides to proceed, the second value it returns 
becomes the value of cerror. 

Common Lisp defines another calling sequence for this function: 

(cerror continue-fonnat-string error-format-string args...) 

This signals an error of flavor eh :common-lisp-cerror, which prints an error message 
using errorfonnat-string and args. It allows one proceed type, whose documentation is 
continue-fonnat-string, and which proceeds silently, returning nil from cerror. cerror can 
tell which calling sequence has been used and behaves accordingly. 

warn format-string &rcst args 

Prints a warning on ‘error-output* by passing the args to format, starting on a fresh 
line, and then returns. 

If *break-on-warnings* is non-nil, however, warn signals a procedable error, using the 
arguments to make an error message. If the user proceeds, warn simply returns. 

•break-on-warnIngs* 

If non-nil, warn signals an error rather than just printing a message. 

check-type place type-spec [descriptioii[ Macro 

check-arg-type place type-spec [description] Macro 

Signals a correctable error if the value of place docs not fit the type type-spec, place is 
something that setf can store in. type-spec is a type specifier, a suitable second argument 
to typep, and is not evaluated (see section 2.3, page 14). A simple example is: 
(check-type foo (integer 0 10)) 

'Phis signals an error unless (typep foo ’{integer 0 10)); that is, unless foo’s value is an 
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integer between zero and ten, inclusive. 

If an error is signaled, the error message contains the name of the variable or place where 
tlte erroneous value was found, and the erroneous value itself. An Hnglish description of 
tlie type of object that was wanted is computed automatically from the type specifier for 
use in the error message. Kor the commonly used type specifiers this computed 
description is adequate. If it is unsatisfactory in a particular case, you can specify 
(Jescripiion, which is used instead. In order to make the error message grammatical, 
description should start with an indefinite article. 

The error signaled is of condition sys:wrong-type-argument (see page 61). fhe proceed 
type :argument-value is provided. If a handler priKceds using this proceed type, it 
should specify one additional argument; tliat value is stored into place with setf. ITie 
new value is tlien tested, and so on. check-type returns when a value passes the test. 

check-arg-type is an older name for tills macro. 

check-arg mr-name predicate description [type-symbol\ Macro 

check-arg is an obsolete variant of check-type, predicate is either a symbol which is 
predicate (a function of one argument) or a list which is a form. If it is a predicate, it is 
applied to die value of mr-name, which is valid if the predicate returns non-nil. If it is a 
form, it is evaluated, and the value is valid of the form returns non-nil. The form ought 
to make use of var-name, but nothing checks this. 

There is no way to compute an English description of valid values from predicate, so a 
description string must always be supplied. 

type-symbol is a symbol that is used by condition handlers to determine what type of 
argument was expected. If predicate is a symbol, you may omit type-symbol, and 
predicate is used for diat purpose as well. The use of the type-symbol is not really well- 
defined, and check-type, where a type specifier serves both purposes, is superior to 
check-arg for this reason. 

Examples: 

(check-arg foo stringp "a string") 

(check-arg h 

(or (stringp h) (typep h ’fs:host)) 

"a host name" 
fs:host) 

Other fiinctions that can be used to test for invalid values include ecase and cease (page 
66), which arc error-checking versions of selectq, and etypecase and ctypecase (page 21), 
error-checking versions of typecase. 


PS:<I..MAN>HRRORS.TEXT.102 


8-JUN-84 



I isp Machine Manual 


711 


Signaling Conditions 


assert icsi-fonn [(phucs...) [string <?rgs...]] Macro 

Signals an ciTor if test-form evaluates to nil. The rest of the assert form is relevant only 
if the error happens. 

First of all. the places are forms tliat can be stored into with setf. and which arc used 
(presumably) in test-form. The reason that the places arc specified again in tlic assert is 
so that the expanded code can arrange for the user to be able to specify a new value to 
be stored into any one of tliem when he proceeds from the error. When the error is 
signaled, one prrK’ccd-lypc is provided for each plaee that is given. The condition object 
has flavor eh:failed-assertion. 

If the user docs proceed with a new value in tliat fashion, the test-form is evaluated 
again, and the error repeals until die test-form comes out non-nil. 

I'he string and args arc used to print tlic error message. If they arc omitted, "Failed 
assertion" is used. They arc evaluated only when an error is signaled, and arc evaluated 
again each time an error is signaled, setf'ing the places may also involve evaluation, 
which happens each time the user proceeds and sets one. 

Example: 

(assert (neq (car a) (car b)) ((car a) (car b)) 

"The CARS of A and B are EQ; ~S and ~S" 

(car a) (car b)) 

The places here arc (car a) and (car b). The args happen to be the same two forms, by 
not-cxactly-coincidcnce; the current values of the places arc often useful in tlic error 
message. 

I'he remaining signaling functions are provided for compatibility only, 
error &rcst make-condition-arguments 

error exists for compatibility with Maclisp and the Symbolics version of Zetalisp. It takes 
arguments in three patterns: 

(error string object [zH/em/p/]) 
which is used in Maclisp, and 

(error condition-instance) 

(error flavor^name init-options. . .) 

which are used by Symbolics. (In fact, the arguments to error are simply passed along to 
make-condition if they do not appear to fit the Maclisp pattern). 

If the Maclisp argument pattern is not used tlien there is no difference between error and 
ferror. 

cHterror format-string &rest args 

'I’he (Tommon Lisp version of error signals an uncorrectablc error whose error message is 
printed by passing format-string and args to format. 
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fsignal formai-stmg «&rcst formai-args 

This funclion is for Symbolics compalibilily only, and is equivalent to 

(cerror :no-action nil nil formal-siring fomial-args...) 

signal signal-name &rest remaining-make-condilion-argumenls 

llie signal-name and remaining-make-eondilion-argumenis are passed to make-condition, 
and llie result is signaled with signal-condition. 

If the remaining-make-eondilion-argumenls are keyword arguments and :proceed-types is 
one of tlie keywords, the associated value is used as the list of proceed types. In 
particular, if signal-name is actually a condition instance, so tliat the remaining arguments 
will be ignored by make-condition, it works to specify the proceed types this way. 

If the prcKecd types are not specified, a list of all the proceed types tliat the condition 
instance knows how to prompt tlie user about is used by default, 

errset form [/Zog] Macro 

Catches errors during the evaluation of form. If an error occurs, the usual error message 
is printed unless flag is nil. Then control is tlirown and the errset-form returns nil. flag is 
evaluated first and is optional, defaulting to t. If no error occurs, the value of the errset- 
form is a list of one element, die value of form. 

errset is an old. Maclisp construct, implemented much like condition-case. Many uses 
of errset or errset-like constructs really ought to be checking for more specific conditions 
instead. 

catch-error fonn \flag\ Macro 

catch-error is a variant of errset. This construct catches errors during the evaluation of 
fonn and returns two values. If fonn returns normally, the first value is fon7i's first value 
and the second value is nil. If an error occurs, the usual error message is printed unless 
flag is nil, and dien control is thrown out of the catch-error form, which returns two 
values, first nil and second a non-nil value Uiat indicates the occurrence of an error, flag 
is evaluated before fonn and is optional, defaulting to t. 

errset 

If this variable is non-nil, errset forms are not allowed to trap errors, 
entered just as if there were no errset. This is intended mainly for 
initial value of errset is nil. 

gpp Macro 

This is for Maclisp compatibility only and should not be used. 

(err) is a dumb way to cause an error. If executed inside an errset, that errset returns 
nil, and no message is printed. Otherwise an error is signaled with error message just 
"ERROR»". 

(err foni\) evaluates fonn and causes the containing errset to return the result If 
executed when not inside an errset, an error is signaled with form's value printed as the 
error message. 


Variable 

The debugger is 
debugging. The 
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(err form flog), which exists in Maclisp, is not supported. 


30.5.2 CYeating Condition Instances 

You can create a condition instance quite satisfactorily with make-instance if you know 
which insutnee variables to initialize, b'or example, 

(make-instance ’ferror :condition-names ’(foo) 

:format-string "~S loses." 

:format-args losing-object) 

creates an instance of ferror just like the one dial would be signaled if you do 
(terror ’foo "~S loses." losing-object) 

Note that the flavor name and its components’ names are added in automatically to whatever 
you specify for the :condition-names keyword. 

Direct use of make-instance is cumbersome, however, and it is usually handier to define a 
signal name with defsignal or defsignal-explicit and tlien create tlie instance with make- 
condition. 

A signal name is a sort of abbreviation for all tlie things tliat are always the same for a 
certain sort of condition: the flavor to use, the condition names, and what arguments are 
expected. In addition, it allows you to use a positional syntax for die arguments, which is usually 
more convenient than a keyword syntax in simple use. 

Here is a typical defsignal: 

(defsignal series-not-convergent sys:arithnietic-error (series) 
"Signaled by limit extractor when SERIES does not converge.") 

This defines a signal name series-not-convergent, together with die name of the flavor to use 
(sys:arithmetic-error, whose meaning is being stretched a little), an interpretation for the 
arguments (series, which is explained below), and a documentation string. The documentation 
string is not used in printing the error message; it is documentation for the signal name. It 
becomes accessible via (documentation ’series-not-convergent ’signal). 

series-not-convergent could then be used to signal an error, or just to create a condition 
instance: 

(ferror ’series-not-convergent 

"The series ~S went to infinity." myseries) 

(make-condition ’series-not-convergent 

"The series ~S went to infinity." myseries) 

The list (series) in the defsignal is a list of implicit instance variable names. They are 
matched against arguments to make-condition following the format string, and each implicit 
instance variable name becomes an operation defined on the condition instance to return the 
corresponding argument. (You can imagine that :gettable-instance-variables is in effect for all 
die implicit instance variables.) In this example, sending a :series message to the condition 
instance returns the value specified via myseries when the condition was signaled. The implicit 
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instance variables arc actually inipleincntcd using the condition instance's property list. 

Thus, defsignal spares you the need to create a new flavor merely in order to remember a 
particular datum about tlic condition. 

defsignal Macro 

signal-name {flavor condition-names...) implicit-instance-variables documentation 
extra-init-keyword-fonnS 

Defines signal-name to create an instiincc of flavor with condition names condition-names. 
and implicit instance variable whose names arc utken from tlic list implicit-instance- 
variables and whose values arc token from the make-condition arguments following the 
fonnat string. 

Instead of a list {flavor condition-names...) there may appear just a flavor name. 'ITtis is 
equivalent to using signal-name as the sole condition name. 

The extra-init-keyword-forms arc fonns to be evaluated to produce additional keyword 
arguments to pass to make-instance. 'I’hcsc can be used to initialize other instance 
variables that particular flavors may have. 'I'hese expressions can refer to the implicit- 
instance-variables. 

documentation is a string which is recorded so that it can be accessed via the ftmetion 
documentation, as in (documentation signal-name ’signal). 

defsignal-expllcit Macro 

signal-name {flavor condition-names...) signal-arglist documentation 
init-keyword-forms... 

Like defsignal, defsignal-explicit defines a signal name. 'Phis signal name is used the 
same way, but tlie way it goes about creating die condition instance is different. 

First of all, there is no list of implicit instance variables. Instead, signal-arglist is a 
lambda list which is matched up against all the arguments to make-condition except for 
the signal-name itself. I’he variables bound by tlie lambda list can be used in the init- 
keyword-forms, which are evaluated to get arguments to pass to make-instance. For 
example: 

(defsignal-explicit mysigna1-3 

(my-error-f1avor mysigna1-3 my-signals-category) 
(format-string losing-object &rest format-args) 

"The third kind of thing I like to signal." 

:format-string format-string 

:format-args (cons losing-object (copylist format-args)) 

:losing-object-name (send losing-object :name)) 

Since implicit instance variables are really Just properties on the property list of the 
instance, you can create them by using init keyword :property-list. TTie contents of the 
property list determines what implicit instance variables exist and their values. 
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make-condition ,s7g/w/-/w//;r &rcst arguments 

make-condition is the fundamental way that condition instances arc created. The signal- 
name Siiys how to interpret tlic arguments and come up with a flavor and values for its 
instance variables. The handling of tlic arguments is entirely detennined by the signal- 
name. 

If signal-name is a condition instance, make-condition returns it. It is not useful to call 
make-condition this way explicitly, but this allows condition instances to be passed to 
the convenience functions error and signal which call make-condition. 

If tlic signal-name was defined with defsignal or defsignal-explicit, then that definition 
specifics exactly how to interpret the arguments and create the instance. In general, if the 
signal-name has an eh:make-condition-function property (which is what defsignal 
defines), this property is a function to which the signal-name and arguments arc passed, 
and it docs tlic work. 

Alternatively, the signal-name can be the name of a flavor, i’hcn the arguments are 
passed to make-instance, which interprets them as init keywords and values. This mode 
is not really recommended and exists for compatibility with Symbolics software. 

If the signal-name has no ehimake-condition-function property and is not a flavor name, 
then a trivial defsignal is assumed as a default. It looks like this: 

(defsignal signal-name fervor ()) 

So the value is an instance of ferror, with the signal-name as a condition name, and the 
arguments are interpreted as a format string and args for it. 

ITie signal-name nil actually has a definition of this form, nil is frequently used as a 
signal name in the function ferror when there is no desire to use any condition name in 
particular. 

30.5.3 Signaling a Condition Instance 

Once you have a condition instance, you are ready to invoke the condition handling 
mechanism by signaling it, A condition instance can be signaled any number of times, in any 
stack groups. 

signal-condition condition-instance &optional proceed-types invoke-debugger 
ucode-error-status inhibit-resume-handlers 

Invoke the condition handling mechanism on condition-instance. The list of proceed-types 
says which proceed types (among those conventionally defined for the type of condition 
you have signaled) you are prepared to implement, should a condition handler return one 
(see “proceeding”). These are in addition to any proceed types implemented nonlocally by 
condition-resume forms. 

ucode-error status is used for internal purposes in signaling errors detected by tlie 
microcode. 
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signal-condition tries various possible handlers for the condition. First eh:condition- 
handlers is scanned for handlers that are applicable (according to the condition names they 
specify) to this condition instance. After this list is exhausted, ehxondition-default-handlers is 
scanned the same way. 1-ach handler tliat is tried can terminate the act of signaling by tluowing 
out of signal-condition, or it can specify a way to prtKced from the signal. The handler can 
also return nil to decline to handle the condition: tlicn the next possible handler is offered a 
chance. 

If all handlers decline to handle the ct)ndition and invoke-debugger is non-nil, the debugger is 
the handler Of last resort. With die debugger, the user can ask to tlirow or to proceed. The 
default value of invoke-dehugger is non-nil if the condilion-inslance is an error. 

If all handlers decline to act and iuvoke-debugger is nil, signal-condition prcKCcds using the 
first proceed type on tlie list of available ones, provided it is a nonlocal prtKcCd type. If it is a 
local proceed type, or if there are no proceed types, signal-condition just returns nil. (It would 
be slightly simpler to proceed using tlic first prtxeed type whether it is local or not. But in the 
case of a local proceed type, tliis would Just mean returning the proceed type instead of nil. It is 
considered slightly more useful to return nil, allowing the signaler to distinguish the case of a 
condition not handled. 'Ihe signaler knows which proceed types it specified, and can if it wishes 
consider nil as equivalent to the first of tltem.) 

Otherwise, by this stage, a pnxecd type has been chosen from the available list. If the 
proceed type was among those specified by tlie caller of signal-condition, tlicn proceeding 
consists simply of returning to that caller, llic chosen proceed type is die first value, and 
arguments (returned by the handler along with the proceed type) may follow it. If the proceed 
type was implemented nonlocally with condition-resume (sec page 723), then the associated 
proceed handler function on ehxondition-resume-handlers is called. 

If inhibit-resume-handlers is non-nil, resume handlers are not invoked. If a handler returns a 
nonlexal proceed type, signal-condition just returns to its caller as if the proceed type were local. 
If the condition is not handled, signal-condition returns nil. 

The purpose of condition-bind-default is so that you can define a handler that is allowed to 
handle a signal only if none of tlie callers' handlers handle it. A more flexible technique for 
doing this sort of thing is to make an ordinary handler signal the same condition instance 
recursively by calling signal-condition, like tliis: 

(multiple-value-list 

(signal-condition condition-instance 

eh:condition-proceed-types nil nil t)) 

ITiis passes along tlie same list of proceed types specified by the original signaler, prevents the 
debugger from being called, and prevents resume handlers from being run. If the first value 
signal-condition returns is non-nil, one of the outer handlers has handled the condition; your 
handler’s simplest option is to return those same values so that tlie other handler has its way (but 
it could also examine them and return modified values). Otherwise, you go on to handle the 
condition in your default manner. 
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Variable 


This variable may be set to a list of condition names to be tnu cd. Whenever a condition 
possessing a traced condition name is signaled, an error is signaled to report tlie fact. 
(Tracing of conditions is turned olT while Uiis error is signaled and handled). Proceeding 
with proceed type :no-action causes tlie signaling of tlie original condition to continue. 

If eh:trace-conditions is t, all conditions arc traced. 

30.6 Proceeding 

Both condition handlers and the user (through the debugger) have the option of proceeding 
certain conditions. 

liiich condition name can define, as a convention, certain proceed types, which arc keywords 
that signify a certain conceptual way to proceed. For example, condition name sys:wrong-type- 
argument defines tlie proceed type :argument-value which means, “Here is a new value to use 
as the argument.” 

Each signaler may or may not implement all the proceed types which are meaningful in 
general for the condition names being signaled. For example, it is futile to prcKccd from a 
sys:wrong-type-argument error with :argument-value unless the signaler knows how to take the 
associated value and store it into the argument, or do something else that fits the conceptual 
specifications of :argument-value. For some signalers, it may not make sense to do tliis at all. 
Therefore, one of the arguments to signal-condition is a list of the proceed types tliat this 
particular signaler knows how to handle. 

In addition to the proceed types specified by the individual signaler, other proceed types can 
be provided nonlocally; they are implemented by a resume handler which is in effect Uirough a 
dynamic scope. See below, section 30.6.3, page 723. 

A condition handler can use the operations :proceed-types and ;proceed-type-p on the 
condition instance to find out which proceed types are available. It can request to proceed by 
reluming one of the available proceed types as a value. This value is returned from signal- 
condition, and the condition’s signaler can take action as appropriate. 

If the handler returns more than one value, the remaining values are considered arguments of 
the proceed type. The meaning of the arguments to a proceed type, and what sort of arguments 
are expected, are part of the conventions associated with the condition name that gives the 
proceed type its meaning. For example, the :argument-value proceed type for sys:wrong-type- 
argument errors conventionally takes one argument, which is the new value to use. All the 
values returned by the handler are returned by signal-condition to the signaler. 

Here is an example of a condition handler that proceeds from sys:wrong-type-argument 
errors. It makes any atom effectively equivalent to nil when used in car or any other function 
that expects a list. The handler uses tlie :description operation, which on sys:wrong-type- 
argument condition instances returns a keyword describing the data type that was desired. 
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(condition-bind 

{(sys;wrong-type-argument 
#’(lambda (condition) 

(if (eq (send condition :description) ’cons) 
(values .-argument-value nil))))) 

body...) 


Here liic argument to tlic :argument-value proceed type is nil. 

. proceed-types «« condition 

Returns a list of die proceed types available for this condition instance. This operation 
should be used only within the signaling of the condition instance, as it refers to the 
special variable in which signal-condition stores its second argument. 

. proceed-type-p proceed-type Operalioii on condition 

t if proceed-type is one of the proceed types available for this condition instance. This 
operation should be used only within die signaling of die condition instance, as it refers 
to the special variable in which signal-condition stores its second argument. 

30.6.1 Proceeding and the Debugger 

If the condition invokes the debugger, then the user has the opportunity to proceed. When 
die debugger is entered, the available proceed types are assigned command characters starting with 
Super-A. Each character becomes a command to proceed using the corresponding proceed type. 

Three additional facilities arc required to make it convenient for the user to proceed using the 
debugger. Each is provided by methods defined on condition flavors. When you define a new 
condition flavor, you must provide methods to implement these facilities. 

Documentation; 

It must be possible to tell the user what each proceed type is for. 

Prompting for arguments: 

The user must be asked for the arguments for the proceed type. Each proceed type may 
have different arguments to ask for. 

Not always the same proceed types: 

Usually tlic user can choose among the same set of proceed types that a handler can, but 
sometimes it is useful to provide the user with a few extra ones, or to suppress some of 
tlicm for him. 


fhese three facilities are provided by methods defined on condition flavors. Each proceed 
type that is provided by signalers should be accompanied by suitable methods. This means that 
you must normally define a new flavor if you wish to use a new proceed type. 

The :document-proceed-type operation is supposed to print documentation of what a 
proceed type is for. For example, when sent to a condition instance describing an unbound 
variable error, if the proceed type specified is :new-value, the text printed is something like 
“Proceed, reading a value to use instead,” 
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: document-proceed-type pwcccd-typc stream Operation an condWion 

Prints on stream a description of the purpose of proceed type proeeed-type. I'his operation 
uses :case method combination (sec section 21.11, page 433), to make it convenient to 
define the way to drKument an individual prtK'Ccd type. The string printed should sUtrt 
with an imperative verb form, capitalized, and end with a period. P-xamplc: 

'this example is an :or method so tliat it can consider any priKccd type. If it returns 
non-nil. the system considers that it has handled the proceed type and no other methods 
get a chance, ehrplaces is an instance variable of tlic flavor sysdailed-assertion; its 
values arc the proceed types tliis method understands. 

(defmethod (sys:failed-assertion :or :document-proceed-type) 

(proceed-type stream ignore) 

(when (memq proceed-type eh:places) 

(format stream 

"Try again, setting ~S.~ 

You type an expression for it." 
proceed-type) 
t)) 

As a last resort, if the condition instance has a :case method for ;proceed-asking-user 
with proceed'type as the suboperation, and this mctltod has a documentation string, it is 
printed. ITiis is in fact tlic usual way that a proceed type is documented. 

The :proceed-asking-user operation is supposed to ask for suitable arguments to pass with 
the proceed type. Sending :proceed-asking-user to an instance of sysiunbound-variable with 
argument :new-value would read and evaluate one expression, prompting appropriately. 

jproceed-asking-user Operar/on on condition 

proceed-type continuation read-objecl-fn 

'The mctliod for :proceed-asking-user embodies the knowledge of how to prompt for 
and read the additional arguments that go with proceed-type. 

;case method combination is used (see section 21.11, page 433), making it possible to 
define the handling of each proceed type individually in a separate function. 'The 
documentation string of tlie ;case mctliod for a proceed type is also used as the default 
for ;document-proceed-type on that proceed type. 

The argument continuation is an internal function of the debugger which actually proceeds 
from the signaled condition if the iproceed-asking-user method calls it. This is the 
only way to cause proceeding actually to happen. Call continuation with funcall, giving a 
proceed type and suitable arguments. ITic proceed type passed to continuation need not 
be the same as the one given to .-proceed-asking-user; it should be one of the proceed 
types available for handlers to use. 

Alternatively, the :prompt-and-read method can return without calling continuation-, 
then the debugger continues to read commands. 'The options which the fs:no-more-room 
condition offers in the debugger, to run Dired or expunge a directory, work this way. 
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I'hc itrguinoiu rcad-objat-Jh is another internal function of liie debugger whose purpose is 
to read arguments from the user or request confirmation. If you wish to do those things, 
you must funcall mul-ohjecl-fuiniion to do it. Use the calling sequence documented for 
the function prompt-and-read (sec page 45.^). (The read-ohjed-fu may or may not 
actually use prompt-and-read.) 

Merc is how sys:proceed-with-value-mixin provides for the puKced type :new-value. Note 
the d(Kumentation string, which is automatically use by :document-proceed-type since no :case 
method for that operation is provided. 

{definethod (proceed-»ith-value-mixin 

rcase :proceed-asking-user :new-va1ue) 

(continuation read-object-function) 

"Return a value; the value of an expression you type." 

(funcall continuation :new-value 

(funcall read-object-function 
:eval-read 

"~&Form whose value to use instead: "))) 

The :user-proceed-types operation is given the list of proceed types actually available and is 
supposed to return tlie list of pri^ecd types to oflcr to die user. Hy default, tliis operation 
returns its argument: all prtKccd types are available to the user tlirough tlie debugger. 

For example, the condition name sys:unbound-variable conventionally defines tlie proceed 
types :new-value and :no-action. 'fhe first specifics a new value; Utc second attempts to use the 
variable’s current value and gets another error if the variable is still unbound. 'I'hcsc arc clean 
operations for handlers to use. But it is more convenient for the user to be offered only one 
choice, wliich will use tlie variable's new value if it is bound now, but otherwise ask for a new 
value. This is implemented with a :user-proceed-types method that replaces tlie two proceed 
types witli a single one. 

Or, you might wish to offer the user two different proceed types that differ only in how they 
ask the user for additional information. For handlers, tlierc would be only one proceed type. 

Finally, tlicre may be priKced types intended only for the debugger which do not actually 
proceed; these should be inserted into the list by the :user-proceed-types method. 

; user-proceed-types proceed-types Openiiion on condition 

Assuming that procecd-types is the list of proceed types available for condition handlers to 
return, tliis operation returns the list of proceed types tliat the debugger should offer to 
the user. 

Only the prcKccd types offered to the user need to be handled by idocument-proceed- 
type and :proceed-asking-user. 

The flavor condition itself defines this to return its argument. Other condition flavors 
may redefine this to filter the argument in some appropriate fashion. 
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:pass-on method combination is used (see section 21.11, page 433), so that if multiple 
mixins define mctliods for :user-proceed-types, each method gets a chance to add or 
remove prcKCcd types. I hc methods should not actually modify tlic argument, but should 
cons up a new list in which certain keywords are added or removed according to tlic 
other keywords tliat are tlicre. 

Hlcmcnts should be removed only if they arc specifically recognized, this is to say, the 
mctliod should make sure that any unfamiliar elements present in the argument arc also 
present in tlic value. Arranging to omit certain specific proceed types is legitimate: 
returning only the intersection with a constant list is not legitimate. 

Mere is an example of nontrivial use of :user-proceed-types: 

(defflavor my-error () (error)) 

(defmethod (my-error :user-proceed-types) (proceed-types) 

(if (memq :foo proceed-types) 

(cons :foo-two-args proceed-types) 
proceed-types)) 

(defmethod (my-error :case :proceed-asking-user ;foo) 

(cont read-object-fn) 

"Proceeds, reading a value to foo with." 

(funcall cont :foo 

(funcall read-object-fn :eva1-read 
"Value to foo with: "))) 

(defmethod (my-error :case :proceed-asking-user :foo-two-args) 

(cont read-object-fn) 

"Proceeds, reading two values to foo with." 

(funcall cont :foo 

(funcall read-object-fn :eval-read 
"Value to foo with: ") 

(funcall read-object-fn :eval-read 

"Value to foo some more with: "))) 

In this example, if the signaler provides the prtx:eed type ;foo, then it is described for the 
user as “proceeds, reading a value to foo with”: and if the user specifics that proceed type, he is 
asked for a single value, which is used as the argument when pr(x:eeding. In addition, the user 
is offered the proceed type :foo-two-args, which has its own dtKumentation and which reads 
two values. But for condition handlers Utere is really only one proceed type, :foo. :foo-two- 
args is just an alternate interface for the user to proceed type :foo, and this is why the :user- 
proceed-types method offers :foo-two-args only if the signaler is willing to accept :foo. 
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30.6.2 How Sljjiiulers Provide Proceed Types 

Bach condition name defines a conceptual meaning for certain proceed types, but this docs 
not mean that all of those proceed types may be used every time the condition is signaled. 1110 
signaler must specifically implement the proceed types in order to make them do what lliey arc 
conventionally supposed to do. For some signalers it may be difficult to do. or may not even 
make sense. For example, it is no use having ti pnK'eed type :store-new-value if tlic signaler 
docs not have a suitable place to store, permanently, the argument the handler supplies. 

rhcreforc. we require each signaler to specify just which prtKced types it implements. Unless 
the signaler explicitly specifies proceed types one way or another, no prtx'ccd types arc allowed 
(except for nonUxal ones, described in tlic following section). 

One way to specify tlic pnxeed types allowed is to call signal-condition and pass the list of 
proceed types as the second argument. 

Another way tliat is less general but more convenient is signal-proceed-case. 

slgnal-procead-case {{variables...) make-condiiion-arguweius...) clauses... Macro 

Signals a condition, providing proceed types and code to implement them. Each clause 
specifics a prcxccd type to provide, and also contains code to be run if a handler should 
proceed with that proceed type. 

(signal -proceed-case ( {argument-vars.,.) 

signal-name signal-name-arguments...) 

{proceed-type forms ...) 

{proceed-type forms .. .) 

...) 

A condition-object is created with make-condition using the signal-name and signal-name- 
arguments’, then it is signaled giving a list of the proceed types from all the clauses as the 
list of proceed types allowed. 

The variables argumenl-vars are bound to the values returned by signal-condition, except 
for the first value, which is tested against the proceed-type from each clause, using a 
selectq. ITie clause that matches is executed. 

lixample: 

(defsignal my-wrong-type-arg 

(eh:wrong-type-argument-error sys:wrong-type-argument) 
(old-value arg-name description) 

"Wrong type argument from my own code.") 

(signal-proceed-case 
((newarg) 

’my-wrong-type-arg 

"The argument ~A was ~S, which is not a cons." 

’foo foo ’cons) 

(;argument-value (car newarg))) 
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I'he signal name my-wrong-type-arg creates errors with condition name sys:wrong-type- 
argument. The signal-proceed-case shown signals such an error, and handles the proceed type 
:argument-value. If a handler proceeds using that pnx'eed type, the handler’s value is put in 
newarg, and tlien its car is returned from the signal-proceed-case. 

30.6.3 Nonlocal Proceed Types 

When the caller of signal-condition specifies proceed types, these are called local proceed 
types. I'hey are implemented at the point of signaling. There are also nonlocal proceed types. 
which arc in effect for all conditions (with appropriate condition names) signaled during the 
execution of the body of die establishing macro. Wc say that the macro establishes a resume 
handler for tlic pnKced type. 

riic most general construct for establishing a resume handler is condition-resume. For 
example, in 

(condition-resume 

’(fs:file-error :retry-open t 

("Proceeds, opening the file again.") 

(lambda (ignore) (throw ’tag nil))) 

(do-forever 

(catch ’tag (return (open pathname))))) 
the proceed type :retry-open is available for all fs:file-error conditions signaled within the call to 
open. 

condition-resume handler-fontt &body body Macro 

cond1t1on-pesume-1f cond-fomt handler-form &body body Macro 

Both execute body with a resume handler in effect for a nonlocal proceed type according 
to tlic value of handler-form. For condition-resume-if, the resume handler is in effect 
only if cond-fonn's value is non-nil. 

The value of the handler-fonn should be a list with at least five elements: 

( condition-names proceed-type predicate format-string-and-args 
handler-function addilional-args ...) 

condition-names is a condition name or a list of them. The resume handler applies to 
these conditions only. 

proceed-type is the proceed type implemented by this resume handler. 

predicate is either t or a function that is applied to a condition instance and determines 
whether the resume handler is in effect for that condition instance. 

fonnat-string-and-args is a list of a string and additional arguments that can be passed to 
format to print a description of what this proceed type is for. These are needed only for 
anonymous proceed types. 

handler-function is the function called to do the work of proceeding, once this proceed 
type has been returned by a condition handler or the debugger. 
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catch-error-restart-explicit-if makes it easy to esuiblish a particular simple kind of resume 
handler. 

catch-error-restart-0xpl1c1t-if Macro 

cotnl-form (condition-names proceed-lype fonnal-siring fonnal-args,..) body... 
Hxecutes body with (if cond-fonn produces a non-nil value) a resume handler for prcKCcd 
type proceed-lype and condition(s) condition-names, condition-names should he a symbol or 
a list of symbols; it is not evaluated, proceed-type should be a symbol. 

If pixK'eeding is done using this resume handler, control returns from the catch-error- 
restart-explicit-if form. 'I’he first value is nil and the second is non-nil. 

format-string and the fonnal-args, all of which arc evaluated, arc used by the 
:document-proceed-type operation to describe the proceed type, if it is anonymous. 

F-or condition handlers there is no distinction between liKal and nonlocal prcKccd types. 'I'hey 
arc both included in Uic list of available pnx:ecd types returned by the :proceed-types operation 
(all the local proceed types come first), and the condition handler selects one by returning the 
proceed type and any conventionally associated arguments. ITie debugger’s ;user-proceed-types, 
:document-proceed-type and :proceed-asking-user operations are also make no distinction. 

rhe difference comes after tlic handler or the debugger returns to signal-condition, if the 
proceed type is a local one (one of those in the second argument to signal-condition), signal- 
condition simply returns. If the proceed type is not among those the caller handles, signal- 
condition looks for a resume handler associated with the proceed type, and calls its handler 
function. The arguments to tlic handler function are the condition instance, the addilional-args 
specified in the resume handler, and any arguments returned by the condition handler in addition 
to the proceed type. The handler function is supposed to do a throw. If it returns to signal- 
condition, an error is signaled. 

You are allowed to use “anonymous” nonlocal proceed types, which have no conventional 
meaning and are not specially known to the :document-proceed-type and .proceed-asking- 
user operations. The anonymous proceed type may be any Lisp object. The default definition of 
:proceed-asking-user handles an anonymous proceed type by simply calling the continuation 
passed to it, reading no arguments. The default definition of ;document-proceed-type handles 
anonymous pr(x:eed types by passing format the fonnat-string-and-args list found in the resume 
handler (this is what Uiat list is for). 

Anonymous proceed types arc often lists. Such proceed types are usually made by some 
variant of error-restart, and they are treated a little bit specially. For one thing, they are all put 
at the end of the list returned by the :proceed-types operation. For another, the debugger 
command Control-C or Resume never uses a proceed type which is a list. If no atomic proceed 
type is available. Resume or Control-C is not allowed. 


error-restaPt (condition-names fonnat-string fonnat-args...) body... Macro 

error-restart-loop Macro 

catch-errop-restart Macro 

catch-error-restart-If Macro 


cond-fonn (condition-names format-string format-args...) body... 
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All execute body with an anonymous resume handler for amdition-names. The piwccd 
type for this resume handler is a list, so the Resume key will not use it. condition-names 
is either a single condition name or a list of tlicm, or nil meaning all conditions; it is not 
evaluated. 

format-string and die format-args, all of which arc evaluated, arc used by the 
:document-proceed-type operation to describe the anonymous pnKced type. 

If the resume handler made by error-restart is invoked by proceeding from a signal, the 
automatically generated resume handler function docs a dirow back to the error-restart 
and die body is executed again from the beginning. If body returns, die values of the 
last form in it arc returned from the error-restart form. 

error-restart-loop is like error-restart except diat it loops to the beginning of body 
even if body completes nonnally. It is like enclosing an error-restart in an iteration. 

catch-error-restart is like error-restart except that it never loops back to die beginning. 
If the anonymous proceed type is used for proceeding, die catch-error-restart form 
returns widi nil as the first value and a non-nil second value. 

catch-error-restart-if is like catch-error-restart except that die resume handler is only 
in effect if die value of the cond-fonn is non-nil. 

All of diese variants of error-restart can be written in terms of condition-resume-if. 

These forms are typically used by any sort of command loop, so that aborting within the 
command loop returns to it and reads another command, error-restart-loop is often right for 
simple command loops, catch-error-restart is useful when aborting should tenninate execution 
rather than retry, or with an explicit conditional to test whether a throw was done. 

error-restart forms often specify (error sys:abort) as the condition-names. The presence of 
error causes them to be listed (and assigned command characters) by the debugger, for all errors, 
and the presence of sys:abort causes the Abort key to use diem. If you would like a precede 
type to be offered as an option by the debugger, but do not want the Abort key to use it, 
specify just error. 

eh:tnvoke-resume-handler condition-instance proceed-type &rest args 

Invokes the innermost applicable resume handler for proceed-type. Applicability of a 
resume handler is determined by matching its condition names against those possessed by 
condition-instance and by applying its predicate, if not t, to condition-instance. 

If proceed-type is nil, the innermost applicable resume handler is invoked regardless of its 
proceed type. However, in this case, the scan stops if t is encountered as an element of 
eh condition - resu me - handlers. 
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eh:cond1t1on-resume-han(ners Variable 

The currcnl list of resume handlers for nonlocal priKced types, condition-resume works 
by binding this variable. Hlcmcnts arc usually lists tliat have tlic format described above 
under condition-resume. The symbol t is also meaningful as an clement of tliis list. It 
terminates the scan for a resume handler when it is made by signal-condition for a 
condition that was not handled, t is pushed onto die list by break loops and the 
debugger to shield the evaluation of your type-in from automatic invocation of resume 
handlers established outside the break loop or tlie error. 

The links of this list, and its elements, are often created using with-stack-list, so be 
careful if you try to save the value outside tlie context in which you examine it. 

sys: abort (condition) CondUion 

I'his condition is signaled by tlie Abort key; it is how that key is implemented. Most 
command loops use some version of error-restart to set up a resume handler for 
sys:abort so tliat it will return to the innennost command loop if (as is usually the case) 
no handler handles it. These resume handlers usually apply to error as well as sys:abort, 
so tliat the debugger will offer a specific command to return to the command loop even if 
it is not the innermost one. 

30.7 The Debugger 

When an error condition is signaled and no handlers decide to handle the error, an interactive 
debugger is entered to allow tlie user to look around and see what went wrong, and to help him 
continue the program or abort it. 'This section describes how to use the debugger. 


30.7.1 Entering the Debugger 

There are two kinds of errors; those generated by the Lisp Machine’s microcode, and those 
generated by Lisp programs (by using terror or related functions). When there is a microcode 
error, the debugger prints out a message such as the following: 

»TRAP 5543 (TRANS-TRAP) 

The symbol FOOBAR is unbound. 

While in the function LOSE-XCT *■ LOSE-COMMAND-LOOP *• LOSE 

The first line of this error message indicates entry to the debugger and contains some 
mysterious internal microcode infonnation: the micro program address, the microcode trap name 
and parameters, and a microcode backtrace. Users can ignore this line in most cases. The second 
line contains a description of the error in English. 'The third line indicates where the error 
happened by printing a very abbreviated “backtrace” of the stack (see below); in the example, it 
is saying that the error was signaled inside the function lose-xct, which was called by lose- 
command-loop. 

Here is an example of an error from Lisp code: 

>>ERR0R: The argument X was 1, which is not a symbol, 

While in the function FOO *■ SIiEVALl ^ SI:LISP-TOP-LEVELl 
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Here llic first line contains the Hnglish description of the error message, and the second line 
contains the abbreviated backtrace, foo signaled die error by calling terror; however, terror is 
censored out of the backtrace. 

After the debugger’s initial message, it prints tbe function that got tlie error and its 
arguments. 'I'hen it prints a list of commands you can use to proceed from the error, or to abort 
to various command loops, fhe possibilities depend on the kind of error and where it happened, 

so the list is dillcrent each time; that is why the debugger prints it. The commands in the list all 

start with Super-A, Super-B and continue as fitr as is necessary. 

eh:*inh1bit-debugger-proceed-ppompt* Vorkible 

If this is non-nil. the list of Super commands is not printed when the debugger is 
entered. Type Help P to see die list. 

fhe debugger normally uses the stream *debug-io* for all its input and output (see page 

460). By default it is a synonym for *terminal-io*. I’he value of this variable in die stack group 

in which the error was signaled is the one that counts. 

0h:*debug-io-ov8Pr1de* Variable 

If this is non-nil, it is used by the debugger instead of die value of ’debug-io*. The 
value in the stack group where the error w'as signaled is die one that counts. 

The debugger can be manually entered cidier by causing an error (c.g. by typing a ridiculous 
symbol name such as ahsdgf at die Lisp rcad-eval-prinl loop) or by typing the Break key with 
the Meta shift held down while the program is reading from die tcnninal. Typing the Break key 
with both Control and Meta held down forces die program into the debugger immediately, even 
if it is running. If the Break key is typed without Meta, it puts you into a rcad-cval-print loop 
using the break function (see page 795) rather than into the debugger. 

eh &optional process 

Causes process to enter the debugger, and directs the debugger to read its commands from 
the ambient value of ’terminal-io*. current when you call eh, rather than process ’s own 
value of ’terminal-io* which is what would be used if process got an error in the usual 
way. The process in which you invoked eh waits while you arc in the debugger, so there 
is no ambiguity about which process will handle your keyboard input 

If process had already signaled an error and was waiting for exposure of a window, then 
it enters the debugger to handle that error. Otherwise, die break condition is signaled in 
it (just like what Control-Meta-Break docs) to force it into the debugger. 

The Resume command makes process resume execution. You can also use other debugger 
commands such as Abort, Control-R, Control-Meta-R and Control-T to start it up 
again. Exiting the debugger in any way causes eh to return in its process. 

process can also be a window, or any flavor instance which understands die :process 
operation and returns a process. 

If process is not a process but a stack group, the current state of the stack group is 
examined. In this case, die debugger runs in “cxamine-only” mode, and executes in the 
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process in which you invoked eh. You cannot resume execution of the debugged stack 
group, but Resume exits the debugger. It is your responsibility to ensure that no one 
tries to execute in die stack group being debugged while die debugger is looking at it. 

If process is nil, eh finds all the processes waiting to enter die debugger and asks you 
which one to use. 

30.7.2 How to Use the Debugger 

Once inside the debugger, the user may give a wide variety of commands. 'ITiis section 
describes how to give the commands, then explains diem in approximate order of usefulness. A 
summary is provided at die end of the listing. 

When die debugger is waiting for a command, it prompts with an arrow: 

-» ■ 

If the error took place in the evaluation of an expression that you typed at the debugger, you 
are in a second level (or deeper) error. 'ITie number of arrows in the prompt indicates the depth. 

ITic debugger also warns you about certain unusual circumstances that may cause paradoxical 
results. For example, if default-cons-area is anything except working-storage-area, a message 
to that effect is printed. If ’read-base* and ’print-base* are not die same, a message is 
printed. 

At this point, you may type either a Lisp expression or a command; a Control or Meta 
character is interpreted as a command, whereas most normal characters are interpreted as the first 
character of an expression. If you type the Help key or the ? key, you can get some 
introductory help with the debugger. 

If you type a Lisp expression, it is interpreted as a Lisp form and evaluated in the context of 
the current frame, lliat is, all dynamic bindings used for the evaluation arc those in effect in the 
current frame, with certain exceptions explained below. The results of the evaluation are printed, 
and die debugger prompts again with an arrow.. If, during the typing of the form, you change 
your mind and want to get back to the debugger’s command level, type the Abort key or a 
Control-G; the debugger responds with an arrow prompt. In fact, at any time that input is 
expected from you, while you arc in the debugger, you may type Abort or Control-G to cancel 
any debugger command that is in progress and get back to command level. Control-G is useful 
because it can never exit from the debugger as Abort can. 

This read-eval-print loop maintains the values of +, *, and - almost like the Lisp listen 
loop. I'hc difference is that some single-character debugger commands such as C-M-A also set * 
and + in dicir own way. 

If an error occurs in the evaluation of the IJsp expression you type, you may enter a second 
invocation of die debugger, looking at the new error. The prompt in this event is to make it 
clear which level of error you are examining. You can abort the computation and get back to the 
first debugger level by typing the Abort key (sec below). 
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Various debugger commands ask for Lisp objects, such as an object to return or the name of 

a catcli-Uig. You must type a form to be evaluated: its value is the object that is actually used. 

This provides greater generality, since there arc objects to which you might want to refer that 
cannot be typed in (such as arrays). If the form you type is non-trivial (not just a constant fonn), 
tlic debugger shows you the result of the evaluation and asks for confimiation before proceeding. 
If you answer negatively, or if you abort, the command is canceled and the debugger returns to 
command level. Once again, the special bindings in effect for evaluation of the form arc those of 
the current frame you have selected. 

fhe Meta-S and Control-Meta-S commands allow you to look at the bindings in effect at 
the current frame. A few variables arc rebound by the debugger itself whenever a user-provided 

fonn is evaluated, so you you must use Meta-S to find tlic values they actually had in the erring 

computation. 

*terminal-io* *terminal-io* is rebound to the stream the debugger is using. 

’standard-input* 

’standard-output* 

’standard-input’ and ’standard-output* are rebound to be synonymous with 
’terminal-io*. 

+ , + +, + + + 

*,”,*”.’values* 

+ and * are rebound to the debugger’s previous form and previous value. 
Commands for examining arguments and such, including C-M-A, C-M-L and 
C-M-V, leave * set to the value examined and + set to a locative to where the 
value was found. When the debugger is first entered, + is the last fonn typed, 
which is typically the one that caused the error, and * is the value of tlie previous 
form. 

oval hook 

applyhook These variables (see page 748) are rebound to nil, turning off the step facility if 
it was in use when the error occurred. 

eh;condition-handlers 

eh:condition-default-handlers 

These arc rebound to nil, so that errors occurring within forms you type while in 
the debugger do not magically resume execution of the erring program. 

eh:condition-resume-handlers 

To prevent resume handlers established outside the error from being invoked 
automatically by deeper levels of error, this variable is rebound to a new value, 
which has an element t added in the front. 


PS:<L.MAN>DKBLIG.TEXT.21 


8-JL'N-84 



Tlic Debugger 


730 


l isp Miiehinc Miinual 


30.7.3 l)el)ug}>cr Commands 

All debugger commands arc single characicrs, usually with the Control or Meta bits. 'ITic 
single most useful command is Abort (or ControDZ), which exits from the debugger and throws 
out of the compuUttion that got the error. ( This is die Abort key, not a 5-lcttcr command.) Often 
you arc not interested in using the debugger at all and just want to get back to l.isp top level: so 
you can do this in one keystroke. 

If the error happened while you were innocently using a system utility such as tlic editor, 
then it represents a bug in tlic system. Report die bug using die debugger command Control-M. 
This gives you an editor preinitiali/cd with die error mcssiige and a backtrace. You should type 
in a precise description of what you did that led up to die problem, dicn send the mcssiige by 
typing End. Be as complete as possible, and always give die exact commands you typed, exact 
filenames, etc. radicr then general descriptions, as much as possible. ITie person who investigates 
the bug report will have to try to make the problem happen again; if he docs not know where to 
find your file, he will have a difficult time. 

The Abort command signals the sys:abort condition, returning control to the most recent 
command loop. This can be l.isp top level, a break, or the debugger command loop associated 
with another error. Typing Abort multiple times throws back to successively older read-cval-print 
or command loops until top level is reached. I’yping Meta-Abort, on the other hand, always 
dirows to top level. Meta-Abort is not a debugger command, but a system command that is 
always available no matter what program you arc in’. 

Note that typing Abort in the middle of typing a fonn to be evaluated by the debugger 

aborts that form and returns to die debugger’s command level, while typing Abort as a debugger 

command returns out of die debugger and the erring program, to the previous command level. 
Typing Abort after entering a numeric argument just discards the argument. 

Self-documentation is provided by the Help or ? command, which types out some 
documentation on die debugger commands, including any special commands that apply to the 
particular error currently being handled. 

Often you want to try to proceed from the error. When the debugger is entered, it prints a 
table of commands you can use to proceed, or abort to various levels. The commands are 
Super-A, Super-B, and so on. How many there are and what they do is different each time 
there is an error, but the table says what each one is for. If you want to sec the table again, 
type Help followed by P. 

1’hc Resume (or Control-C) command is often synonymous with Super-A. But Resume 

only proceeds, never aborts. If there is no way to proceed, just ways to abort, then Resume 

docs not do anything. 

’fhe debugger knows about a current stack frame, and there arc several commands that use it. 
fhe initially current stack frame is the one which signaled the error, either the one which got the 
microcode-detected error or tlie one which called ferror, cerror, or error. When the debugger 
suirts it up it shows you this frame in the following format: 
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FOO: 

Arg 0 (X): 13 

Arg 1 (Y): 1 

and so on. 'I his means that foo was called with two arguments, whose names (in the Lisp source 
code) arc x and y. The current values of x and y arc 13 aild 1 respectively. 'I’hcsc may not be 
the original arguments if foo liappcns to setq its arguhicnt variables. 

The Clear-Screen (or Control-L) command clears tlic screen, retypes the error message that 
was initially printed when die debugger was entered, and prints out a description of the current 
flame, in tlic above format. 

Several commands arc provided to allow you to examine tlic l.isp control stack and to make 
frames current other than tlic one that got tlic error. The control suick (or “regular pdl”) keeps a 
record of all functions currently active. If you call foo at l.isp’s top level, and it calls bar, which 
in turn calls baz, and baz gets an error, tlicn a backtrace (a backwards trace of die stack) would 
show all of this information. I'lic debugger has two backtrace commands. Control-B simply 
prints out the names of die functions on the stack; in the above example it vvould print 
BAZ BAR ^ FOO ♦- SI:*EVAL 

SI:LISP-T0P-LEVEL1 <- SI: LISP-TOP-LEVEL 
The arrows indicate the direction of calling. The Meta-B command prints a more extensive 
backtrace, indicating the names of die arguments to the functions and their current values; for 
die example above it might look like: 

BAZ: 

Arg 0 (X): 13 

Arg 1 (Y): 1 

BAR: 

Arg 0 (ADDEND): 13 
FOO: 

Arg 0 (FROB): (A B C . D) 

and so on. ITie backtrace commands all accept numeric arguments which say how many frames 
to describe, the default being to describe all the frames. 

Moving around in the stack: 

ITie Control -N command makes the “next” older frame be current. This is the frame which 
called the one that was current at before. The new current frame’s function and arguments are 
printed in the format shown immediately above. 

Control-P moves the current frame in the reverse direction. If you use it immediately after 
getting an error it selects frames that are part of the act of signaling. 

Meta-< selects the frame in which the error occurred, die same frame that was selected when 
the debugger was entered. Meta-> selects the outermost or initial stack frame. Control-S asks 
you for a string and searches down the stack (toward older frames) from the current frame for a 
frame whose executing function's name contains that string. That frame becomes current and is 
printed out. These commands are easy to remember since they are analogous to editor commands. 
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Hie Control-Meta-N, Controt-Meta-P, and Control-Meta-B commands arc like tlic 
corresponding Control commands but don’t censor tlic stack to omit “uninteresting” functions. 
When looking at intcipretcd code, the debugger usually tries to skip over frames Uiat belong to 
the functions composing the interpreter, such as eval, prog, and cond. Control-Meta-N, 
Control-Meta-P, and Control-Meta-B show everything. I'hcy also show frames that arc not yet 
active; that is, frames whose arguments arc still being computed for functions that arc going to 
be called. The Control-Meta-U ewnmand goes down the stack (to older frames) to the next 
interesting function and makes that the current frame. 

Meta-L prints out tlic current frame in “full screen" format, which shows the arguments and 
their values, the local variables and their values, and the machine code with an arrow pointing to 
the next instruction to be executed. Refer to chapter 31, page 752 for help in reading this 
machine code. 

Commands such as Control-N and Control-P. which arc useful to issue repeatedly, take a 
prefix numeric argument and repeat tliat many types. 'I’hc numeric argument is typed by using 
Control or Meta and tlic number keys, as in tlic editor. Some other commands such as Control- 
M also use die numeric argument; refer to the table at the end of tlic section for detailed 
information. 

Resuming execution: 

Meta-C is simitar to Control-C, but in tlic ease of an unbound variable or undefined 
tlmction, actually setqs the variable or defines the function, so that the error will not happen 
again. Control-C (or Resume) provides a replacement value but docs not actually change the 
variable. Meta-C prcKceds using the proceed type :store-new-value, and is available only if 
that proceed type is provided. 

Control-R is used to return a value or values from the current frame; the frame that called 
that frame continues running as if tlie function of the current frame had returned. This command 
prompts you for each value that the caller expects; you can type either a form which evaluates to 
the desired value or End if you wish to return no more values. 

The Control-T command does a throw to a given tag with a given value; you are prompted 
for the tag and the value. 

Control-Meta-R reinvokes the current frame; it starts execution at the beginning of the 
function, with the arguments currently present in die stack frame. Ihese are the same arguments 
the function was originally called with unless eitlier the function itself has changed them with setq 
or you have set diem in the debugger. If the function has been redefined in the meandme 
(perhaps you edited it and fixed its bug) the new definition is used. Control-Meta-R asks for 
confirmation before resuming execution. 

Meta-R is similar to Control-Meta-R but allows you to change the arguments if you wish. 
You are prompted for the new arguments one by one; you can type a form which evaluates to 
the desired argument, or Space to leave that argument unchanged, or End if you do not want 
any more arguments. Space is allowed only if this argument was previously passed, and End is 
not allowed for a required argument. Once you have finished specifying the arguments, you must 
confirm before execution resumes. 
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Stepping through function calls and returns: 

You can request a trap to die debugger on exit from a particular frame, or die next time a 
function is called. 

Hach stack frame has a “trap on exit” bit. The Control-X command toggles this bit. 'Hie 
Meta-X command sets the bit to cause a trap for the current frame and all outer frames. If a 
program is in an infinite loop, this is a good way to find out how far back on the shick die loop 
is taking place. This also enables you to see what values are being returned. The Control-Meta- 
X command clears die trap-on-exit bit for the current frame and outer frames. 

I'he Control-D command proceeds like Control-C but requests a trap die next time a 
function is called. The Meta-D command toggles the trap-on-next-call bit for die erring stack 
group. It is useful if you wish to set die bit and then resume execution with something other 
than Control-C. The function breakon may be used to request a trap on calling a particular 
function. Trapping on entry to a frame automatically sets the trap-on-exit bit for that frame; use 
Control-X to clear it if you do not want another trap. 

Transfering to other systems: 

Control-E puts you into the editor, looking at the source code for the function in the current 
frame. This is useflrl when you have found the function that caused the error and that needs to 
be fixed. The editor command Control-Z will return to the debugger, if it is still there. 

Control-M puts you into the editor to mail a bug report. The error message and a backtrace 
are put into the editor buffer for you. A numeric argument says how many frames to include in 
the backtrace. 

Control-Meta-W calls the window debugger, a display-oriented debugger. It is not 
documented in this manual, but should be usable without further documentation. 

Examining and setting the arguments, local variables, and values: 

Control-Meta-A takes a numeric argument, n, arid prints out the value of the nth argument 
of the current frame. It leaves * set to the value of the argument, so that you can use the Lisp 
read-eval-print loop to examine it. It also leaves + set to a locative pointing to the argument 
on the stack, so that you can change that argument (by calling rplacd on the locative). Control- 
Meta-L is similar, but refers to the nth local variable of the frame. Control-Meta-V refers to 
the nth value this frame has returned (in a trap-on-exit). Control-Meta-F refers to the function 
executing in the frame; it ignores its numeric argument and doesn’t allow you to change the 
function. 

Another way to examine and set the arguments, locals and values of a frame is with the 
functions eh-arg, eh-loc, eh-val and eh-fun. Use these functions in expressions you evaluate 
inside the debugger, and they refer to the arguments, locals, values and function, respectively, of 
the debugger's current frame. 
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I'hc names eh:arg, eh;val, etc. arc for compatibility with the Symbolics system. 

eh-arg arg-uumber-oi^mme 
8h:arg arg-numbet^oMwme 

When used in an expression evaluated in tlic debugger, eh-arg returns the value of the 
spccifcd argument in tlic debugger’s current frame. Argument names are compared 
ignoring packages: only the pnamc of the symbol you supply is relevant, eh-arg can 
appear in sett and locf to set an argument or get its location. 

eh-loc local-number-or'name 
eh:1oc local-numbcror-name 

1-ikc eh-arg but accesses tlie current frame’s local variables instead of its arguments. 

eh-val &optional value-number-or'name 
eh:va1 &optional value-numbei'or-name 

eh-val is used in an expression evaluated in the debugger when the current frame is 
returning multiple values, to examine those values, 'lliis is only useful if die function has 
already begun to return some values (as in a trap-on-exit), since otherwise they are all nil. 
If a name is specified, it is looked for in die function’s values or return-list declaration, 
if any. 

eh-val can be used with setf and locf. You can make a frame return a specific sequence 
of values by setting all but die last value with eh-val and doing Control-R to return the 
last value. , 

eh-val with no argument returns a list of all the values this frame is returning. 

eh-fun 
eh:fun 

eh-fun can be called in an expression being evalued inside the debugger to return the 
function-object being called in the current frame. It can be used with setf and locf. 

30.7.4 Summary of Commands 

Prints argument list of function in current frame. 

Sets * to the nth argument of the current frame. 

Prints brief backtrace. 

Prints longer backtrace. 

Prints longer backtrace with no censoring of “uninteresting” functions. 

Attempts to continue, using the first proceed type on die list of available 
ones for this error. 

Attempts to continue, setq’ing the unbound variable or otherwise 
“permanently” fixing the error. This uses the proceed type :store-new- 
value, and is available only if that proceed type is. 


Control-A 
Control-Meta-A 
Control-B 
Meta-B 

Control-Meta-B 
Control-C or Resume 

Meta-C 
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Control-D 
Meta-D 

Control-E 

Control-Meta-F 
Control-G or Abort 

Control-Meta-H 


Attempts to continue like Control-C, but trap on the next function call. 

Joggles llic flag that causes a trap on tlic next function call after you 
continue or otherwise exit the debugger. 

Switches to /.macs to edit tlic source code for die function in the current 
frame. 

Sets * to the function in the current frame. 

Quits to command level. This is not a command, but something you can 
type to escape from typing in an argument of a command. 

Describes die condition handlers and resume handlci's established by the 
current frame. 


Control-L or Clear-Screen 

Redisplays error message and current frame. 

Meta-L Displays the current frame, including local variables and compiled code. 

Control-Meta-L Sets * to die value of local variable u of the current frame. 

Control-M Sends a bug report containing the error message and a backtrace of n 

frames (default is 3). 


Control-NorLine 

Meta-N 

Control-Meta-N 

Control-P or Return 
Meta-P 

Control-Meta-P 

Control-R 
Meta-R 

Control-Meta-R 

Control-S 

Meta-S 

Control-Meta-S 

Control-T 


Moves to die next (older) frame. With argument, moves down n frames. 

Moves to next frame and displays it like Meta-L. With argument, move 
down n frames. 

Moves to next frame even if it is “uninteresting” or still accumulating 
arguments. With argument, moves down n frames. 

Moves up to previous (newer) frame. With argumenh moves up n frames. 

Moves to previous frame and displays it like Meta-L. With argument, 
moves up n frames. 

Moves to previous frame even if it is “uninteresting” or sdll accumuladng 
arguments. With argument, moves up n frames. 

Returns a value or values from the current frame. 

Reinvokes the function in the current frame (restart its execution at the 
beginning), optionally changing the arguments. 

Reinvokes the function in the current frame widi the same arguments. 

Searches for a frame containing a specified function. 

Reads the name of a special variable and returns that variable’s value in 
the current frame. Instance variables of self may also be specified even if 
not special. 

Prints a list of special variables bound by the current frame and the values 
they arc bound to by the frame. If the frame binds self, all the instance 
variables of self are listed even if they are not special. 

Throws a value to a tag. 
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Control-Meta-U 
Control-X 

Meta-X 

Control-Meta-X 

Control-Meta-V 

Control-Meta-W 
Control-Z or Abort 

? or Help 
Meta-< 


Moves down the stack to the previous “interesting” frame. 

Toggles the flag in flic current frame fliat causes a trap on exit or throw 
through that frame. 

Sets the flag causing a trap on exit or throw flirough the frame for the 
current frame and all the frames outside of it. 

Clears the flag causing a trap on exit or throw through the frame for the 
current frame and all flic frames outside of it. 

Sets * to the /;th value being returned from the current frame. I’his is 
non-nil only in a trap on exit from the frame. 

Switches to the window-oriented debugger. 

Aborts the computation and throw back to the most recent break or 
debugger, to flie program’s command level, or to Lisp top level. 

Prints debugger command self-documentation. 

Moves to the frame in which the error was signaled, and makes it current 
once again. 


Meta-> Moves to the outermost (oldest) stack frame. 

Control-0 flirough Control-Meta-9 

Numeric arguments to the.following command are specified by typing a 
decimal number with Control and/or Meta held down. 


Super-A, etc. ITic commands Super-A, Super-B, etc. are assigned to all flic available 

proceed types for this error. 'The assignments arc different each time the 
debugger is entered, so it prints a list of them when it starts up. Help P 
prints the list again. 


30.7.5 Deexposed Windows and Background Processes 


If the debugger is entered in a window that is not exposed, a notification is used to inform 
you that it has happened. 

In general, a notification appears as a brief message printed inside square brackets if flie 
selected window can print it. Otherwise, blinking text appears in the mouse dcKumcntation line 
telling you that a notification is waiting: to sec the notification, type Terminal N or select a 
window that can print it. In ciflicr case, an audible beep is made. 

In flie case of a notification that the debugger is waiting to use a deexposed window, you can 
select and expose the window in which the error happened by typing Terminal OS. You can do 
this even if the notification has not been printed yet because the selected window cannot print it. 
If you select the waiting window, in this way or in any otlier way, the notification is discarded 
since you already know what it was intended to tell you. 

If the debugger is entered in a process that has no window or other suitable stream to type 
out on, tlie window system assigns it a “background window”. Since this window is initially not 
exposed, a notification is printed as above and you must use Terminal 0 S to see the window. 
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If an error happens in the scheduler stack group or the first level error handler suick group 
which are needed for processes to function, or in die keyboard or mouse prcK'css (both needed 
for the window system to function), die debugger uses the cold load slreanu a primitive facility 
for terminal I/O which bypasses the window system. 

If an error happens in another process but the window system is locked so that the 
notification mechanism cannot function, the cold load stream is used to ask what to do. You can 
tell die debugger to use the cold load stream immediately, to forcibly clear die window system 
locks and notify immediately as above, or to wait for the locks to become unlocked and then 
notify as above. If you tell it to wait, you can resume operation of die machine. Meanwhile, 
you can use the command Terminal Control-Clear-Input to forcibly unlock die locks, or 
Terminal Call to tell the debugger to use the cold load stream. The latter command normally 
enters a break-loop that uses die cold-load stream, but if there are any background errors, it 
offers to enter die debugger to handle diem. You can also handle die errors in a l isp listen loop 
of your choice by means of die function eh (page 727), assuming you can select a functioning 
L.isp listen loop. 

30.7.6 Debugging after a Warm Boot 

After a warm boot, die process that was running at the time of booting (or at the time the 
machine crashed prior to booting) may be debugged if you answer 'no’ when the system asks 
whether to reset that process. 

si:debug-warm-booted-proc9SS 

invoke the debugger, like the function eh (page 727), on the process that was running as 
of the last warm boot (assuming there was such a process). 

On the CADR, the state you sec in the debugger is not correct; some of the information 
dates from some period of time in advance of the boot or the crash. 

On the Lambda, the state you see in the debugger will, in some system version, be accurate. 

30.8 Tracing Function Execution 

The trace facility allows the user to trace some functions. When a function is traced, certain 
special actions are taken when it is called and when it returns. The default tracing action is to 
print a message when die function is called, showing its name and arguments, and another 
message when the function returns, showing its name and value(s). 

The trace facility is closely compatible with Maclisp. You invoke it through the trace and 
untrace special forms, whose syntax is described below. Alternatively, you can use the trace 
system by clicking Trace in the system menu, or by using the Meta-X Trace command in the 
editor. This allows you to select the trace options from a menu instead of having to remember 
the following syntax. 
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trace Special fonu 

A trace form looks like: 

(trace spec-1 spec-2 ...) 

F^icli spec can take any of the following forms: 

a symbol lliis is a furKtion name, with no options. The function is traced In the 
default way. printing a message each time it is called and each time it 
returns. 

a\\sX(funclion-name opfioii-l optioii-2...) 

fiinclion-iianie is a symbol and the opiions control how it is to be traced. 
'I he various options are listed below. Some options U>ke arguments, which 
should be given immediately following tlie option name. 

aWst (AmeXion funclion-spec opiion-l opfion-2...) 

'Ibis is like the previous form except tliat function-spec need not be a 
symbol (see section 11.2, page 223). It exists because if function-name was 
a list in the previous form, it would instead be interpreted as the 
following form: 

a list ((function-1 function-2...) option-1 option-2 

All of tlie functions arc traced with the same options. Each function can 
be either a symbol or a general fttnction-spec. 


1 he following trace options exist: 


:break pred 


:exitbreak pred 


:error 


:step 

:stepcond pred 
:entrycond pred 


•exitcond pred 


Causes a breakpoint to be entered after printing the entry trace 
information but before applying the traced fiinction to Its arguments, if 
and only if pred evaluates to non-nil. During the breakpoint, the symbol 
arglist is bound to a list of the arguments of the function. 

This is just like break except that the breakpoint is entered after the 
function has been executed and the exit trace information has been 
printed, but before control returns. During the breakpoint, the symbol 
arglist is bound to a list of the arguments of the function, and the 
symbol values is bound to a list of the values that the function is 
returning. 

Causes the error handler to be called when the fiinction is entered. Use 
Resume (or Control-C) to continue execution of tlic function. If this 
option is specified, tliere is no printed trace output other than the error 
message printed by the error handler. ITiis is semi-obsolete, as breakon 
is more convenient and does more exactly tlie right thing. 

Causes the function to be single-stepped whenever it is called. See tlie 
documentation on the step facility, section 30.11, page 746. 

Causes the function to be single-stepped only if pred evaluates to non-nil. 

Causes trace information to be printed on function entry only if pred 
evaluates to non-nil. 

Causes trace information to be printed on function exit only if pred 
evaluates to non-nil. 
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:cond pred 
:wherein function 


:argpdl /«// 

:entry print form 

:exitprint form 

:print form 

;entry list 

.-exit list 

:arg :value :both 


This specifies both :exitcond and lentrycond together. 

Causes tlic function to be traced only when called, directly or indirectly, 
from the specified function function. One can give several trace specs to 
trace, all specifying tlic same function but with different wherein options, 
so Uiat the function is traced in dift'erent ways when called from different 
functions. 

This is different from advise-within, which only afi'ccts the function being 
advised when it is called directly from the other function. The trace 
:wherein option means Uiat when tlic traced function is called, the special 
tracing actions occur if the other function is the caller of this function, or 
its caller's caller, or its caller’s caller’s caller, etc. 

Specifics a symbol pdl. whose value is initially set to nil by trace. When 
tlic function is traced, a list of the current recursion level for the function, 
the function’s name, and a list of arguments is consed onto tlic pdl when 
the function is entered, and edr’ed back off when tlic function is exited. 
The pd! can be inspected from within a breakpoint, for example, and 
used to determine the very recent history of die function. This option can 
be used with or without printed trace output. Each function can be given 
its own pdl, or one pdl may serve several functions. 

’Fhe form is evaluated and the value is included in tlie trace message for 
calls to the function. You can give this option multiple times, and all the 
fonti's thus specified are evaluated and printed, \\ precedes the values to 
separate them from the arguments. 

The fonn is evaluated and the value is included in the trace message for 
returns from the function. You can give tliis option multiple times, and 
all the fonn's thus specified are evaluated and printed. W precedes the 
values to separate tliem from the returned values. 

The form is evaluated and the value is included in the trace messages for 
both calls to and returns from the function. Equivalent to :exitprint and 
:entryprint at once. 

This specifies a list of arbitrary forms whose values are to be printed along 
with the usual entry-trace. I'he list of resultant values, when printed, is 
preceded by \\ to separate it from the other information. 

This is similar to entry, but specifies expressions whose values are printed 
with the exit-trace. Again, the list of values printed is preceded by W. 

nil 'fhese specify which of the usual trace printouts should be enabled. If 
:arg is specified, then on function entry the name of the function and the 
values of its arguments will be printed. If rvalue is specified, then on 
function exit the returned value(s) of the function will be printed. If 
:both is specified, botli of these will be printed. If nil is specified, 
neither will be printed. If none of these four options are specified the 
default is to rboth. If any further options appear after one of these, they 
are not treated as options! Rather, they are considered to be arbitrary 
forms whose values are to be printed on entry and/or exit to the function. 
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along with llic nomial trace information. The values printed will be 
preceded by a //, and follow any values specified by :entry or :exit. 

Note tliat since these options "swallow” all following options, if one is 
given it should be tlie last option specified. 

In the evaluation of the expression arguments to various trace options such as :cond and 
:break, ilie value of arglist is a list of the arguments given to the traced function. Thus 
(trace (foo rbreak (null (car arglist)))) 
would cause a break in foo if and only if the first argument to foo is nil. If the :break option is 
used, the variable arglist is valid inside the break-loop. If you setq arglist before actual function 
execution, the arguments seen by the function will change. 

In the evaluation of tlie expression arguments to various trace options such as :cond and 
:break on exit from tlie traced function, die variable values is bound to a list of the resulting 
values of the tniced function. If the rexitbreak option is used, the variables values and arglist 
are valid inside the break-loop. If you setq values, the values returned by the function will 
change. 

The trace specifications may be “factored”, as explained above. For example, 

(trace ((foo bar) :break (bad-p arglist) :value)) 
is equivalent to 

(trace (foo :break (bad-p arglist) rvalue) 

(bar rbreak (bad-p arglist) rvalue)) 

Since a list as a function name is interpreted as a list of functions, non-atomic function names 
(sec section 11.2, page 223) arc specified as follows: 

(trace (rfunction (rmethod flavor rmessage) rbreak t)) 

trace returns as its value a list of names of all functions it traced. If called with no 
arguments, as just (trace), it returns a list of all die functions currently being traced. 

If you attempt to trace a function already being traced, trace calls untrace before setting up 
the new trace. 

Tracing is implemented with encapsulation (sec section 11,9, page 244), so if die function is 
redefined (c.g. with defun or by loading it from a QFASL file) the tracing will be transferred 
from the old definition to the new definition. 

Tracing output is printed on the stream that is the value of ‘trace-output*. ITiis is 
synonymous with ‘terminal-io* unless you change it. 

untrace Special fonn 

Undoes the effects of trace and restores functions to their normal, untraced state, 
untrace accepts multiple specifications, e.g. (untrace foo quux fuphoo). Calling untrace 
with no arguments will untracc all functions currently being traced. 


PS:<l..MAN>DB-AlD.'rFXT.14 


8-JUN-84 



I isp Miicliinc Manual 


741 


IJicakon 


tpace-complle-f lag Variable 

If the value of trace-compile-flag is non-nil, the functions created by trace are 
compiled, allowing you to trace special fonns such as cond without interfering with die 
execution of the tracing functions. The default value of this flag is nil. 

See also the function compile-encapsulations, page 302. 

30.9 Breakon 

'I'hc function breakon allows you to request tliat die debugger be entered whenever a certain 
function is called. 

breakon function-spec «&optional condition-form 

Hncapsulates the definition of function-spcc so diat a trap-on-call (Kcurs when it is called. 
This enters the debugger. A trap-on-cxit will occur when the stack frame is exited. 

\f condition-form is non-nil, its value should be a form to be evaluated each time function- 
spec is called. The trap occurs only if condition-fonn evaluates to non-nil. Omitting the 
condition-fonn is equivalent to supplying t. If breakon is called more dian once for the 
same function-spec and different condition-fonns, the trap occurs if any of the conditions 
are true. 

breakon with no arguments returns a list of the functions diat are broken on. 

Conditional breakons are useful for causing the trap to occur only in a certain stack group. 
This sometimes allows debugging of functions that are being used frequently in background 
processes. 

(breakon ’foo '(eq current-stack-group current-stack-group)) 

If you wish to trap on calls to foo when called from the execution of bar, you can use 
(si:function-active-p ’bar) as the condition. If you want to trap only calls made directly from 
bar, the thing to do is 

(breakon ’(rwithin bar foo)) 
rather than a conditional breakon. 

To break only the w’th time foo is called, do 
(defvar in) 

(breakon ’foo ’(zerop (deef i))) 

Another useful form of conditional breakon allows you to control trapping from the keyboard; 
(breakon ’foo ’(tv:key-state :mode-lock)) 

The trap occurs only when the Mode-Lock key is down. This key is not normally used for 
much else. With this technique, you can successfully trap on functions used by tlie debugger! 
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unbreakon fund ion-spec &t)pti()nal condiliotuil-form 

Kemove the breakon set on function-spec. If conditional-form is specified, remove only 
that condition. Breakons with other conditions arc not removed. 

With no arguments, unbreakon removes all breakons from all functions. 

lo cause the cnciipsulation which implements the breakon to be compiled, call compile- 
encapsulations or set compile-encapsulations-flag non-nil. See page .W2. This may eliminate 
some of the problems tliat occur if you breakon a function such ;is prog tliat is used by the 
evaluator. (A conditional to trap only in one suick group Will help here also.) 

30.10 Advisin)> a Function 

'I'o advise a function is to tell it to do something extra in addition to its actual definition. It 
is done by means of the ftinction advise. 'I’hc something extra is called a piece of advice, and it 
can be done before, after, or around the definition itself. The advice and tlie definition are 
independent, in tliat changing cither one docs not interfere with the other. Each function can be 
given any number of pieces of advice. 

Advising is fairly similar to tracing, but its purpose is different. I’racing is intended for 
temporary changes to a function to give the user information about when and how the function is 
called and when and with what value it returns. Advising is intended for semi-permarient changes 
to what a function actually does. ITie differences between tracing and advising arc motivated by 
this difference in goals. 

Advice can be used for testing out a change to a ftinction in a way that is easy to retract. In 
this case, you would call advise from the terminal. It can also be used for customizing a 
ftinction that is part of a program written by someone else. In this ease you would be likely to 
put a call to advise in one of your source files or your login init file (see page 801), rather than 
modifying the other person’s source code. 

Advising is implemented with encapsulation (see section 11.9, page 244), so if the function is 
redefined (e.g. with defun or by loading it from a QFASL file) the advice will be transferred 
from the old definition to the new definition. 

advise Macro 

A function is advised by the special form 

(advise function class name position 
fonnl form2. ..) 

None of this is evaluated, function is the function to put the advice on. It is usually a 
symbol, but any function spec is allowed (see section 11.2, page 223). The forms are the 
advice; they get evaluated when the function is called, class should be citlier :before, 
.•after, or :around, and says when to execute the advice (before, after, or around the 
execution of die definition of the function). The meaning of :around advice is explained 
a couple of sections below. 

name is used to keep track of multiple pieces of advice on the same ftinction. name is an 
arbitrary symbol that is remembered as the name of this particular piece of advice. If you 
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have no name in mind, use nil; then we say the piece of advice is anonymous. A given 
function and class can have any number of pieces of anonymous advice, but it can have 
only one piece of named advice for any one name. If you try to define a second one, it 
replaces the first. Advice for testing purposes is usually anonymous. Advice used for 
customizing someone clsc’s program should usually be named so that multiple 
customizations to one function have separate names. Then, if you reload a customization 
that is already loaded, it docs not get put on twice. 

posilioii says where to put this piece of advice in relation to others of the same class 
already present on die same function. If position is nil, die new advice goes in die 
default position: it usually goes at the beginning (where it is executed before the other 
advice), but if it is replacing another piece of advice with the same name, it goes in the 
same place diat the old piece of advice was in. 

If you wish to specify the position, position can be die numerical index of which existing 
piece of advice to insert diis one before. Zero means at the beginning: a very large 
number means at the end. Or, position can be the name of an existing piece of advice of 
the same class on the same function; the new advice is inserted before that one. 

For example, 

(advise factorial ibefore negative-arg-check nil 
(if (minusp (first arglist)) 

(ferror nil "factorial of negative argument"))) 

This modifies the (hypothetical) factorial function so that if it is called with a negative 
argument it signals an error instead of running forever. 

advise with no arguments returns a list of advised functions. 

unadvise Macro 

(unadvise Junction class position) 

removes pieces of advice. None of its arguments are evaluated. Junction and class have 
the same meaning as they do in the function advise, position specifics which piece of 
advice to remove. It can be the numeric index (zero means the first one) or it can be the 
name of the piece of advice. 

If some of the arguments are missing or nil, all pieces of advice which match the non-nil 
arguments arc removed. Thus, if Junction is missing or nil, all advice on all functions 
which match the specified class and position are removed. If position is missing or nil, 
then all advice of the specified class on the specified function is removed. If only Junction 
is non-nil, all advice on tliat function is removed. 

The following arc the primitive functions for adding and removing advice. Unlike the above 
special forms, these are functions and can be conveniently used by programs, advise and 
unadvise arc actually macros that expand into calls to these two. 
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si: advise-1 /mhc/hw class name posilion forms 

Adds advice. ITie arguments have the same meaning as in advise. Note tliat the fortns 
argument is noi a &rest argument. 

si:unadvise-1 &optional function class position 

Removes advice. If function or class or position is nil or unspecified, advice is removed 
from all functions or all classes of advice or advice at all positions are removed. 

You can find out manually wlurt advice a function has with grindef, which grinds the advice 
on die function as forms tliat arc calls to advise, nicsc arc in addition to the definition of the 
function. 

'I'o cause die advice to be compiled, call compile-encapsulations or set compile- 
encapsulations-flag non-nil. Sec page 302. 

30.10.1 Designing the Advice 

For advice to interact usefully with the definition and intended purpose of the function, it 
must be able to interface to die data flow and control flow through the fimction. We provide 
conventions for doing this. 

'Fhc list of the arguments to the function can be found in die variable arglist. rbefore advice 
can replace this list, or an clement of it, to change the arguments passed to die definition itself. 
If you replace an element, it is wise to copy die whole list first with 
(setq arglist (copylist arglist)) 

After the function's definition has been executed, the list of the values it returned can be found 
in the variable values. :after advice can set this variable or replace its elements to cause different 
values to be returned. 

All the advice is executed within a block nil so any piece of advice can exit the endre 
fiinction with return. ITie arguments of the return arc returned as the values of the function and 
no further advice is executed. If a piece of ibefore advice does this then die function’s definition 
is not even called. 

30.10.2 raround Advice 

A piece of rbefore or rafter advice is executed entirely before or entirely after the definition 
of die function, raround advice is wrapped around the definition; that is, the call to the original 
definition of the function is done at a specified place inside the piece of raround advice. You 
specify where by putting the symbol rdo-it in that place. 

For example, (+ 5 rdo-it) as a piece of raround advice would add 5 to the value returned 
by the function, ITiis could also be done by (setq values (list (+ 5 (car values)))) as rafter 
advice. 

When there is more than one piece of raround advice, the pieces arc stored in a sequence 
just like rbefore and rafter advice. Then, the first piece of advice in the sequence is the one 
started first. The second piece is substituted for rdo-it in the first one. Fhe tiiird one is 
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substilulcd for :do-it in the second one.* I'hc original definition is substituted for :do-it in tlic 
last piece of advice. 

:around advice can access arglist, but values is not set up until the outermost raround 
advice returns. At tliat time, it is set to the value returned by the :around advice. It is 
reasonable for the advice to receive the values of die ;do-it (e.g. with multiple-value-list) and 
fool with tJvem before returning them (e g. with values-list). 

:afound advice can return from the block at any time, whether the original definition has 
been executed yet or not. It can also override tlie original definition by failing to contain :do-it. 
Containing two instances of :do-it may be useful under peculiar circumstances. If you are 
careless, die original definition may be called twice, but something like 
(if (foo) (+ 5 :do-it) (♦ 2 :do-it)) 
will work reasonably. 

30.10.3 Advising One Function Within Another 

It is possible to advise the function foo only for when it is called directly from a specific 
other function bar. You do this by advising the fiinction specifier (:within bar foo). That works 
by finding all occurrences of foo in the definition of bar and replacing them with #:altered- 
foo-within-bar. (Note that diis is an uninterned symbol.) This can be done even if bar’s 
definition is compiled code. 'Ihe symbol # :altered-foo-within-bar starts off with the symbol 
foo as its definition: then the symbol #:altered-foo-within-bar, radicr than foo itself, is 
advised. Ihc system remembers that foo has been replaced inside bar, so that if you change the 
definition of bar, or advise it, then the replacement is propagated to the new definition or to the 
advice. If you remove all the advice on (within bar foo), so that its definition becomes the 
symbol foo again, then the replacement is unmade and everything returns to its original state. 

(grindef bar) prints foo where it originally appeared, rather than #:altered-foo-within-bar, 
so the replacement is not seen. Instead, grindef prints calls to advise to describe all the advice 
that has been put on foo or anything else within bar. 

An alternate way of putting on this sort of advice is to use advise-within. 

advise-within Macro 

(advise-within wUhin-funclion Junclion-to-advise 
class name position 

forms...) 

advises Junction-lo-advise only when called directly from the function within-function. The 
other arguments mean tlie same thing as with advise. None of them arc evaluated. 

To remove advice from (within bar foo), you can use unadvise on that function specifier. 
Alternatively, you can use unadvise-within. 
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(unadvise-within wilhin-funclion fumlion-lo-advise class posilion) 
removes advice that has been placed on (:within within-funclion fuuctiou-to-advise). Any 
of the four arginncnts may be missing or nil; then dial argument is unconstrained. All 
advice matching whichever arguments are non-nil is removed. For example, (unadvise- 
within foo nil rbefore) removes all :before-advice from anything within foo. (unadvise- 
within) removes all advice placed on anything within anything. By contrast, (unadvise) 
removes all advice, including advice placed on a function for all callers. Advice placed on 
a function not within another specific function is never removed by unadvise-within. 

The function versions of advise-within and unadvise-within are called si:advise-within-1 
and si:unadvise-within-1. advise-within and unadvise-within are macros Uiat expand into calls 
to die other two. 

30.11 Stepping Through an Evaluation 

riie Step facility gives you the ability to follow every step of the evaluation of a form, and 
examine what is going on. It is analogous to a single-step pnxieed facility often found in 
machine-language debuggers. If your program is doing something strange, and it isn’t obvious 
how it’s getting into its strange state, then the stepper is for you. 

There are two ways to enter the stepper. One is by use of the step function, 
step form 

I'his evaluates form with single stepping. It returns the value of form. 

For example, if you have a function named foo, and typical arguments to it might be t and 
3, you could say 

(step ’(foo t 3)) 

to evaluate the form (foo t 3) with single stepping. 

I'he other way to get into the stepper is to use the ;step option of trace (see page 738). If a 
function is traced with the :step option, then whenever that function is called it will be single 
stepped. 

Note diat any ftmetion to be stepped must be interpreted; that is, it must be a lambda- 
expression. Compiled code cannot be stepped by the stepper. 

When evaluation is proceeding with single stepping, before any form is evaluated, it is 
(partially) printed out, preceded by a forward arrow (■») character When a macro is expanded, the 
expansion is printed out preceded by a double arrow (<♦) character. When a form returns a value, 
the form and the values are printed out preceded by a backwards arrow (<-) character; if there is 
more tlian one value being returned, an and-sign (a) character is printed between the values. 
When die stepper has evaluated the args to a form and is about to apply the function, it prints a 
lambda (X) because entering the lambda is the next thing to be done. 

Since the forms may be very long, the stepper docs not print all of a form; it truncates the 
printed representation after a certain number of characters. Also, to show the recursion pattern of 
who calls whom in a graphic fashion, it indents each form proportionally to its level of recursion. 
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After the stepper prints any of these things, it waits for a comnitind from the user. There arc 
several commands U) tell tile stepper how to pixKccd, or to look at what is happening. The 
commands arc: 

Control-N (Next) 

Steps to tlic Next event, then asks for another command. Kvents include beginning to 
evaluate a form at any level or finishing the evaluation of a fonn at any level. 

Space 

Steps to the next event at this level. In other words, continue to evaluate at this level, 
but don’t step anything at lower levels. This is a good way to skip over parts of tlie 
evaluation that don't interest you. 

Control-A (Args) 

Skips over the evaluation of the arguments of this form, but pauses in the stepper before 
calling the function Uiat is die car of the form. 

Control-U(Up) 

Continues evaluating until we go up one level. 'ITiis is like the space command, only 
more so; it skips over anything on die current level as well as lower levels. 

Control-X(cXit) 

Exits; finishes evaluation without any more stepping. 

Control-T (Type) 

Retypes the current form in full (without truncation). 

Control-G (Grind) 

Grinds (i.c. prettyprints) the current form. 

Control-E (Editor) 

Switches windows, to the editor. 

Control-B (Breakpoint) 

Enters a break loop from which you can examine the values of variables and other 
aspects of the current environment. From within this loop, the following variables are 
available: 

step-form the current form, 

step-values the list of returned values, 

step-value the first returned value. 

If you change the values of these variables, you will affect execution. 

Control-L 

Gears the screen and redisplays the last 10. pending forms (forms that are being 
evaluated). 

Meta-L 

Like Control-L, but doesn’t clear the screen. 

Control-Meta-L 

Like Control-L, but redisplays all pending forms. 

? or Help 

Prints documentation on these commands. 
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It is strongly suggested that you write some little function and try the stepper on it. If you 
get a feel for what the stepper docs and how it works, you will be able to tell when it is the 
right thing to use to find bugs. 

30.12 Evalliook 

The evalhook facility provides a “hook” into the evaluator; it is a way you can get a Lisp 
form of your choice to be executed whenever the evaluator is called. Hie stepper uses evalhook, 
and usually it is the only tiling that ever needs to. However, if you want to write your own 
stepper or something similar, tliis is the primitive facility that you can use to do so. 'Hie way this 
works is a bit hairy, but unless you need to write your own stepper you don’t have to worry 
about it. 

evalhook Variable 

•evalhook* Variable 

If die value of evalhook is non-nil, dien special Uiings happen in the evaluator. Its value 
is called die hook function. When a form (any form, even a number or a symbol) is to 
be evaluated, the hook function is called instead. Whatever values the hook function 
returns are taken to be the results of die evaluation. Both evalhook and applyhook are 
bound to nil before the hook function is actually called. 

The hook function receives two arguments: the form diat was to be evaluated, and the 
lexical environment of evaluation. These two arguments allow the hook function to 
perform later, if it wishes, the very same evaluation that die hook was called instead of. 

applyhook Variable 

•applyhook* Variable 

If the value of applyhook is non-nil, it is called the next time the interpreter is about to 
apply a function to its evaluated arguments. Whatever values the apply hook function 
returns arc taken to be the results of calling the other function. Both evalhook and 
applyhook arc bound to nil before the hook function is actually called. 

The hook function receives dircc arguments; the function that was going to be called, the 
list of arguments it was going to receive, and the lexical environment of evaluation. 
These arguments allow the hook function to perform later, if it wishes, the very same 
evaluation that the hook was called instead of 

When cidier die evalhook or the applyhook is called, both variables are bound to nil. ITiey 
arc also rebound to nil by break and by the debugger, and setq’ed to nil when errors are 
dismissed by dirowing to the Lisp top level loop. This provides the ability to escape from this 
mode if something bad happens. 

In order not to impair die efficiency of the Lisp interpreter, several restrictions arc unposed 
on the evalhook and applyhook. Ihey apply only to evaluation—whether in a read-eval-print 
loop, internally in evaluating arguments in forms, or by explicit use of the function eval. They 
do not have any effect on compiled function references, on use of the function apply, or on the 
mapping functions. 
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evalhook form cvulhook applyliook &()ptiona! environmenf 

I'Aaluatcs Jbrm in tlic specified environment, with evalhook and applyliook in cfTect for all 
recursive evaluations of subforms of form. However, tlie evalhook is not called for the 
evaluation of form itself. 

environment is a list which represents the lexical environment to be in effect for tlic 
evaluation of form, nil means an empty lexical environment, in which no lexical bindings 
exist. This is the environment used when eval itself is called. Aside from nil, the only 
reasonable way to get a value to pass for environment is to use the last argument passed 
to a hook function. You must tike care not to use it after the context in which it was 
made is exited, because environments normally contain stack lists which become garbage 
after their stack frames arc popped. 

environment has no effect on die evaluation of a variable which is regarded as special. 
This is always done by examining die value cell. However, environment contains die 
record of die local special declarations currently in effect, so it docs enter in die decision 
of whether a variable is special. 

Here is an example of die use of evalhook: 

I'his function evaluates a form while printing debugging information. 

(defun hook (x) 

(terpri) 

(evalhook x 'hook-function nil)) 

Notice how this function calls evalhook to evaluate the form f, 

:; so as to hook the sub-forms. 

(defun hook-function (f env) 

(let ((v (multip1e-yalue-list 

(evalhook f 'hook-function nil env)))) 

(format t "form: ~S~%values: ~S~%" f v) 

(values-list v))) 

The following output might be seen from (hook ’(cons (car ’(a . b)) ’c)): 
form: (quote (a . b)) 
values: ((a . b)) 
form: (car (quote (a . b))) 
values: (a) 
form: (quote c) 
values; (c) 

(a . c) 

applyhook Junction list-ofargs evalhook applyhook (^optional environment 

Applies Junction to list-ofargs in the specified environment, with evalhook and applyhook 
in effect for all recursive evaluations of subforms of Junctions body. However, applyhook 
is not called for this application of function itself. For more information, refer to the 
definition of evalhook, immediately above. 
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30.13 The MAR 

I'hc MAR facility allows any word or contiguous set of words to be monitored constantly, 
and can cause an error if the words are referenced in a specified manner. The name MAR is 
from the similar device on tlie I TS PDP-lO’s; it is an acronym for ‘Memory Address Register’. 
The MAR checking is done by the l.isp Machine’s memory management hardware, so tlic speed 
of general execution is not significantly slowed down when the MAR is enabled. However, the 
speed of accessing pages of memory containing the locations being checked is slowed down 
somewhat, since every reference involves a microcode trap. 

These are die functions that control die MAR: 

set-map location cycle-type &optional n-words 

Sets die MAR On n-words words, suirting at location, location may be any object. Often 
it will be a locative pointer to a cell, probably created with the locf special form, n-words 
currently defaults to 1, but eventually it may default to the size of the object, cycle-type 
says under what conditions to trap. :read means that only reading die location should 
cause an error, :write means dial only writing die location should, t means that both 
should. To set the MAR to detect setq (and binding) of the variable foo, use 
(set-mar (variable-location foo) :write) 


dear-mar 

'Turns off the MAR. Wann-booting the machine disables the MAR but docs not turn it 
off, i.e. references to the MARed pages arc still slowed down, clear-mar docs not 
currently speed diings back up until the next time the pages arc swapped out; this may 
be fixed some day. 

mar-mode 

(mar-mode) returns a symbol indicating the current state of the MAR. It returns one of: 
nil 'ITie MAR is not set 

:read llic MAR will cause an error if there is a read. 

:write ITie MAR will cause an error if there is a write, 

t I'hc MAR will cause an error if there is any reference. 

Note that using the MAR makes the pages on which it is set somewhat slower to access, until 

the next dmc they arc swapped out and back in again after the MAR is shut off. Also, use of 

die MAR currently breaks the read-only feature if those pages were read-only. 

Proceeding from a MAR break allows the memory reference that got an error to take place, 
and continues die program with the MAR still effective. When proceeding from a write, you 
have die choice of whcUicr to allow the write to take place or to inhibit it, leaving the location 
with its old contents. 
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sys:mar-break (condition) Condiiion 

I'his is the condition, not an error, signaled by a MAR break. 

The condition instance supports tliesc operations: 

:object The object one of whose words was being referenced. 

;offset llie offset within tlic object of tlie word being referenced, 

rvalue I'he value read, or to be written. 

:direction lather :read or :write. 

The pr(x:eed type :no-action simply pr(x;ecds, continuing with the interrupted program as 
if the MAR had not been set. If tlie trap was due to writing, tlie proceed type 
:proceed-no-write is also provided, and causes tlie program to prcKced but does not 
store tlie value in the memory location. 

Most—but not all—write operations first do a read, setq and rplaca both do. This means 
that if the MAR is in :read mode it catches writes as well as reads; however, they trap during 
the reading phase, and consequently tlie data to be written are not yet known. This also means 
that setting tlie MAR to t mode causes most writes to trap twice, first for a read and tlien again 
for a write. So when tlie MAR says that it trapped because of a read, this means a read at the 
hardware level, which may not look like a read in your program. 
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31. How to Read Assembly Language 

Sometimes it is useful to study the machine language code produced by the Lisp Mtichinc’s 
compiler, usually in order to analyze an error, or sometimes to check for a suspected compiler 
problem. This chapter explains how the l.isp Machine’s instruction set works and how to 
understand what code written in tliat instruction set is doing. Fortunately, tlic translation between 
Lisp and this instruction set is very simple; after you get tlic hang of it, you can move back and 
forth between the two representations without much trouble. I'hc following text docs not as.sumc 
any special knowledge about tlic l.isp Machine, altliough it sometimes assumes some general 
computer science background knowledge. 

31.1 Introduction 

Nobody looks at machine language code by trying to interpret cKtal numbers by hand. 
Instead, tlicrc is a program called the Disjisscmblcr which converts the numeric representation of 
the instruction set into a more readable textual representation. It is called the Disassembler 
because it docs the opposite of what an Assembler would do; however, there isn’t actually any 
assembler that accepts tliis input fonnat, since there is never any need to manually write assembly 
language for tlic Lisp Machine. 

1’he simplest way to invoke the Disassembler is with the Lisp function disassemble. Here is 
a simple example. Suppose we type; 

{defun foo (x) 

(assq ’key (get x ’propname))) 

(compile ’foo) 

(disassemble ’foo) 

This defines the function foo, compiles it, and invokes the Disassembler to print out the 
textual representation of the result of the compilation. Here is what it looks like; 

22 MOVE D-PDL FEF|6 I’KEY 

23 MOVE D-PDL ARG|0 ;X 

24 MOVE D-PDL FEF|7 ;’PROPNAME 

25 (MISC) GET D-PDL 

26 (MISC) ASSQ D-RETURN 

T he Disassembler is also used by the Error Handler and the Inspector. When you see stuff 
like the above while using one of these programs, it is disassembled code, in the same format as 
tlic disassemble function uses. Inspecting a compiled code object shows tlic disassembled code. 

Now, what docs this mean? Before we get started, there is just a little bit of jargon to learn. 
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i'hc acronym PDI. stands for i^ish Down l.ist, and means the same thing as Stack: a last-in 
first-out memory. I’hc tcmis PDl, and sutek will be used interchangeably. The I.isp Machine's 
architecture is rather typical of “stack machines"; there is a suick lliat most instructions deal with, 
and it is used to hold values being computed, arguments, and local variables, as well as flow-of- 
contro! information. An important use of the sUick is to pass arguments to instructions, though 
not all instructions take their arguments from the stack. 

The acronym ‘KKF’ sUinds for l-unction Fntry Frame. A FFK is a compiled code object 
produced by the compiler. After the defun form above was evaluated, the function cell of the 
symbol foo contained a lambda expression. Then we compiled die function foo, and the contents 
of the function cell were replaced by a FFF. I’hc printed representation of tlie F'FF for foo 
looks like this: 

#<DTP-FEF-POINTER 11464337 F00> 

The FFF has three parts (this is a simplified explanation): a header with various fixed-format 
fields; a part holding constants and invisible pointers, and die main body, holding die machine 
language instructions, riic first part of die FFF, die header, is not very interesting and is not 
documented here (you can look at it with describe but it won’t be easy to understand). ITie 
second part of the FfT' holds various constants referred to by the ftuiction; for example, our 
function foo references two constants (the symbols key and propname), and so (pointers to) those 
symbols are stored in die FEF. This part of the FEF also holds invisible pointers to the value 
cells of all symbols that the function uses as variables, and invisible pointers to the function cells 
of all symbols that the fiinction calls as ftinctions. 'ITie third part of the FEF holds the machine 
language code itself. 

Now we can read die disassembled code. The first instruction looked like this: 

22 MOVE D-PDL FEF|6 ; ’KEY 

This instruction has several parts. ITie 22 is the address of this instruction. ITie Disassembler 
prints out the address of each instruction before it prints out the instruction, so that you can 
interpret branching instructions when you see them (we haven’t seen one of these yet, but we will 
later). I’he MOVE is an opcode: diis is a MOVE instruction, which moves a datum from one 
place to another. The D-PDL is a desdnation specification. Tlie D stands for ‘Destination’, and 
so D-PDL means ‘Destination-PDL’: the destination of the datum being moved is the PDL. This 
means diat the result will be pushed onto the PDL, rather than just moved to die top; this 
instruction is pushing a datura onto die stack. I’hc next field of the instruction is FEF|6. This is 
an address, and it specifics where the datum is coming from. I’hc vertical bar serves to separate 
the two parts of the address. The part before the vertical bar can be thought of as a base 
register, and the part after the bar can be thought of as being an offset from that register. FEF 
as a base register means the address of the FEF that we are disassembling, and so diis address 
means the location six words into the FEF. So what this instruction docs is to take the datum 
located six words into the FEF, and push it onto the PDL. 'I'hc instruction is followed by a 
comment field, which looks like :’KE'Y. This is not a comment that any person wrote; the 
disassembler produces diese to explain what is going on. The semicolon just serves to start the 
comment, the way semicolons in Lisp code do. In this ease, the body of die comment, ’KEY, is 
telling us that the address field (FEF|6) is addressing a constant (Uiat is what the single-quote in 
’KEY means), and that the printed representation of that constant is KEY, "With the help of this 
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comment we finally get llic real story about wlial tills instruction is doing: it is pushing (a 
pointer to) die symbol key onto the stack. 

Hie next instruction looks like this: 

23 MOVE D-PDL ARG|0 ;X 

This is a lot like the previous instniction: the only difference is that a different "base register” 
is being used in the address. The ARG base register is used for addressing your arguments: 
ARG|0 means that the datum being addressed is die zeroth argument. Again, die comment field 
explains what diat means: the value of X (which was the zeroth argument) is being pushed onto 
the stack. 

The diird instniction is just like the first and second ones; it pushes the symbol propname 
onto the stack. 

The fourth instruction is something new: 

25 (MISC) GET D-PDL 

The first thing we sec here is (MISC). 'Fliis means diat this is one of the so-called 
miscellaneous instructions. TTicre arc quite a few of these instructions. With some exceptions, 
each miscellaneous instniction corresponds to a Lisp function and has the same name as that Lisp 
function. If a Lisp ftmetion has a corresponding miscellaneous instruction, dicn that function is 
hand-coded in Lisp Machine microcode. 

Miscellaneous instructions only have a destination field; they don’t have any address field. 
The inputs to die instruction come from the stack: the top n elements on the stack are used as 
inputs to the instruction and popped off the stack, where n is the number of arguments taken by 
die function. T he result of the function is stored wherever the desdnation field says. In our case, 
the function being executed is get, a Lisp function of two arguments. The top two values will be 
popped off the stack and used as the arguments to get (the value pushed first is the first 
argument, die value pushed second is the second argument, and so on). Tlie result of die call to 
get will be sent to the destination D-PDL; that is, it will be pushed onto the stack. (In case you 
were wondering about how we handle optional arguments and multiple-value returns, the answer 
is very simple: functions diat use either of those features cannot be miscellaneous instructions! If 
you arc curious as to what functions arc hand-microcoded and thus available as miscellaneous 
instructions, you can look at die defmic forms in the file SYS: SYS; DEFMIC LISP.) 

The fifth and last instruction is similar to the fourth: 

26 (MISC) ASSQ D-RETURN 

What is new here is the new value of die destination field. This one is called D-RETURN, 
and it can be used anywhere destination fields in general can be used (like in MOVE instructions). 
Sending somediing to “Destination-Return” means diat this value should be the returned value of 
die function, and diat we should return from diis function. TTiis is a bit unusual in instruction 
sets; rather dian having a “return” instruction, we have a destination diat, when stored into, 
returns from the function. What diis instruction docs, dien, is to invoke the Lisp function assq 
on the top two elements of the stack and return the result of assq as the result of this function. 
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Now', lei’s Uu)k al the program as a whole and see what it did: 

22 MOVE D-PDL FEF|6 ;’KEY 

23 MOVE D-PDL ARGIO :X 

24 MOVE D-PDL FEF|7 ;’PROPNAME 

25 (MISC) GET D-PDL 

26 (MISC) ASSQ D-RETURN 

First it pushes the symbol key. Then it pushes the value of x. Then it pushes the symbol 
propname. riien it invokes get, which pops the value of x and tltc symbol propname off the 
slack and uses tliem as arguments, thus doing the equivalent of evaluating the form (get x 
’propname). The result is left on the sutek; the stack now contains die result of the get on top, 
and the symbol key underneath that. Next, it invokes assq on tltcsc two values, tints doing tltc 
equivalent of evaluating (assq ’key (get x ’propname)). Finally, it returns the value produced 
by assq. Now, tlic original Lisp program we compiled was: 

(defun foo (x) 

(assq ’key (get x ’propname))) 

We can sec that tlie code produced by tlie compiler is correct: it will do tlie same thing as 
the function we defined will do. 

In summary, we have seen two kinds of instructions so far: tlie MOVE instruction, which 
takes a destination and an address, and two of the large set of miscellaneous instructions, which 
take only a destination, and implicitly get their inputs from the stack. We have seen two 
destinations (D-PDL and D-RETURN), and two forms of address (FEF addressing and ARG 
addressing). 

31.2 A More Advanced Example 

Here is a more complex Lisp function, demonstrating local variables, function calling, 
conditional branching, and some other new instructions. 

(defun bar (y) 

(let ((z (car y))) 

(cond ((atom z) 

(setq z (edr y)) 

(foo y)) 

(t 

nil)))) 

The disassembled code looks like this: 


PS:<1 „M AN>C0DK.TF:XT.36 


8-JUN-84 



A More Adviinccd i-lxanipic 756 Lisp Machine Manual 


20 

CAR D-PDL ARGJO 

:Y 

21 

22 

POP LOCAL|0 

BR-NOT-ATOM 27 

:Z 

23 

CDR D-PDL ARG|0 

;Y 

24 

POP LOCAL|0 

;Z 

25 

CALL D-RETURN FEF|6 

;#’F00 

26 

27 

MOVE D-LAST ARGjO 

MOVE D-RETURN ’NIL 

;Y 


The fim instruction here is a CAR instruction. It has the same fonnat as MOVE: there is a 
destination and an address. I'he CAR instruction reads tlie datum addressed by the address, takes 
tlic car of it, and stores tlie result into tlie destination. In our example, tlie first instruction 

addresses tlie /eroth argument, and so it computes (car y); then it pushes tlie result onto the 

stack. 

'fhe next instruction is something new: the POP instruction. It has an address field, but it 
uses it as a destination ratlier tlian as a source. The POP instruction pops the top value olF the 
stack, and stores tliat value into tlie address specified by the address field. In our example, the 
value on the top of the stack is popped off and stored into address LOCALlO. This is a new 
form of address; it means the zeroth local variable, f’hc ordering of the local variables is chosen 
by tlie compiler, and so it is not fully predictable, although it tends to be by order of appearance 
in the code; fortunately you never have to look at these numbers, because the comment field 

explains what is going on. In this case, tlie vari'able being addressed is z. So this instruction 

pops the top value on the stack into the variable z. The first two instructions work together to 
take the car of y and store it into z, which is indeed the first tiling the function bar ought to do, 
(If you have two local variables with the same name, then Uic comment field won’t tell you 
which of the two you’re talking about; you’ll have to figure that out yourself. You can tell two 
local variables with the same name apart by looking at the number in the address.) 

The next instruction is a familiar MOVE instruction, but it uses a new destination: D- 
IGNORE. This means that the datum being addressed isn’t moved anywhere. If so, then why 
bother doing this instruction? The reason is that there is conceptually a set of indicator bits, as 
are found in most modern computers such as the 68000, the Vax, as well as in obsolete 
computers such as the 370. Every instruction that moves or produces a datum sets the indicator 
bits from that datum so that following instructions can test them. So tlie reason that the MOVE 
instruction is being done is so that someone can test the indicators set up by the value that was 
moved, namely the value of z. 

All instructions except the branch instructions set the indicator bits from the result produced 
and/or stored by that instruction. 

The next instfuction is a conditional branch; it changes the flow of control, based on the 
values in the indicator bits, which in this case reflect the value popped by the POP instruction 
21. The branch instruction is BR-NOT-ATOM 27, which means “Branch, if the quantity was not 
an atom, to location 27; otherwise proceed with execution”. If z was an atom, die IJsp Machine 
branches to location 27, and execution proceeds there. (As you can see by skipping ahead, 
location 27 just contains a MOVE instruction, which will cause the function to return nil.) 
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If z is not an atom, the program keeps gt)ing, and tlic CDR instruction is next. This is just 
like the CAR instruction except tliat it Uikcs the edr; tliis instruction pushes the value of (edr y) 
onto the stack, fhe next one pops tliat value off into the variable z. 

There arc just two more instructions left, nicsc two instructions arc our first example of how 
function calling is compiled. It is the only really tricky tiling in the instruction set. Here is how 
it works in our example: 

25 CALL D-RETURN FEF|6 ;#’F00 

26 MOVE D-LAST ARCjO ;Y 

i’hc form being compiled here is (foo y). ITiis means we are applying tlie function which is 
in the function cell of die symbol foo, and passing it one argument, die value of y. The way 
function calling works is in the following three steps, hirst of all, there is a CALL instruction 
that specifies the function object being applied to arguments. I'his creates a new stack frame on 
the stack, and stores the function object there. Secondly, all the arguments being passed except 
die last one arc pushed onto die stack. Thirdly and lastly, die last argument is sent to a special 
destination, called D-LAST, meaning “this is the last argument”. Storing to this desdnation is 
what actually calls the function, noi the CALL instruction itself. 

TTicrc arc two diings you might wonder about this. First of all, when the function returns, 
what happens to the returned value? Well, this is what we use the destination field of the CALL 
instruction for. llie destination of the CALL is not stored into at the time die CALL instruction 
is executed; instead, it is saved on the stack along with the function operation (in the stack frame 
created by die CALL instruction). Then, when the function actually returns, its result is stored 
into that destination. 

The other question is what happens when there isn’t any last argument: that is, when there is 
a call with no arguments at all? This is handled by a special instruction called CALLO. The 
address of CALLO addresses the function object to be called; the call takes place immediately and 
^ the result is stored into the destination specified by the destination field of the CALLO instruction. 

So, let’s look at the two-instruction sequence above. The first instruction is a CALL; the 
function object it specifies is at FEF|6, which the comment tells us is the contents of the function 
cell of foo (the FEF contains an invisible pointer to that function cell). The destination field of 
die CALL is D-RETURN, but we aren’t going to store into it yet; we will save it away in the 
stack frame and use it later. So the function doesn’t return at this poinL even though it says D- 
RETURN in the instruction; this is the tricky part 

Next we have to push all the arguments except the last one. Well, there’s only one 
argumenL so nothing needs to be done here. Finally, we move the last argument (that is, the 
only argument: the value of y) to D-LAST, using the MOVE instruction. Moving to D-LAST is 
what actually invokes the fiinction, so at this point the function foo is invoked. When it returns, 
its result is sent to the destination stored in the stack frame: D-RETURN. Tlicrcfore, the value 
returned by the call to foo will be returned as the value of the function bar. Sure enough, this 
is what the original Lisp code says to do. 
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When the compiler pushes iirguments to :i function call, it somciinies docs it by sending the 
values to a destination called D-NEXT (meaning tlic “next” argument). This is exactly the Siime 
as D-PDL when producing a compiled function. The distinction is important when tlie compiler 
output is passed to die miertKompiler to generate miertKode. 

Here is another example to illustrate function calling. This I.isp function calls one function on 
the results of another function. 

(defun a (x y) 

(b (c X y) y)) 

fhe disassembled code looks like this: 


22 CALL D-RETURN FEF|6 ;#’B 

23 CALL D-PDL FEF|7 ;#’C 

24 MOVE D-PDL ARGjO ;X 

25 MOVE D-LAST ARG|1 ;Y 

26 MOVE D-LAST ARojl :Y 


The first instniction starts off the call to the function b. The destination field is saved for 
later: when this function returns, we will return its result as a’s result Next the call to c is 
started. Its destination field, too, is saved for later; when c returns, its result should be pushed 
onto the stick, so that it will be the next argument to b. Next, the first and second arguments 
to c arc passed: the second one is sent to D-LAST and so the flmction c is called. Its result as 
we said, will be pushed onto the stack, and thus become tlie first argument to b. Finally, the 
second argument to b is passed, by storing in D-LAST; b gets called, and its result is sent to 
D-RETURN and is returned from a. 

31.3 The Rest of the Instructions 

Now that we’ve gotten some of the feel for what is going on, I will start enumerating the 
instructions in the instruction seL The instiuctions fall into four classes. Class I instructions have 
both a destination and an address. Class II instructions have an address, but no destination. 
Class 111 instructions arc the branch instructions, which contain a branch address rather than a 
general base-and-offset address. Class IV instructions have a destination, but no address; these 
are die miscellaneous instructions. 

We have already seen just about ail die Class I instructions. There arc nine of them in all: 
MOVE, CALL, CALLO, CAR, CDR, CAAR, CADR, CDAR, and CDDR. MOVE Just moves a 
datum from an address to a destination; the CxR and CxxR instructions are the same but 
pcrfomi the function on die value before sending it to the desdnation; CALL starts off a call to a 
function with some arguments; CALLO performs a call to a function with no arguments. 

We’ve seen most of the possible fonns of address. So far we have seen the FEF, ARG, and 
LOCAL base registers. There arc two other kinds of addresses. One uses a “constant” base 
register, which addresses a set of standard constants: NIL, T, 0, 1, and 2. 'The disassembler 
doesn’t even boUicr to print out CONSTANTlw, since the number n would not be even slightly 
interesting: it just prints out ’NIL or ’1 or whatever. The other kind of address is a special one 
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printed as PDL-POP, which means that ia read the value at this address, an object should be 
popped off the top of the shick. 

I’hcrc arc more Class II instructions. 'I'hc only one we've seen so far is POP. which pops a 
value off the stack and stores it into tlic specified address. Another, called MOVEM (from the 
PI)P-10 opcode name, meaning MOVH to Memory), stores tlic top element of the stack into tlic 
specified address, but doesn’t pop it oft' the stack. 

Seven Class 11 instructions implement heavily-used two-argument functions: +, *, /, 

LOGAND, LOGXOR, and LOGIOR. Ihcsc instructions take the first argument from the top of 
tlic stack (popping it olf) and their second argument from tlic specified address, and tlicy push 
the result on the stack. Thus die suick level docs not change due to these instructions. Mere is a 
small ftiiiction tliat shows some of these new tilings: 

(defun foo (x y) 

(setq X (logxor y (- x 2)))) 

llic disassembled code looks like this: 

16 MOVE D-PDL ARG|1 

17 MOVE D-PDL ARcjo 

20 - ’2 

21 LOGXOR PDL-POP 

22 MOVEM ARG|0 

23 MOVE D-RETURN PDL-POP 

Instructions 20 and 21 use two of the new Class II instructions: the - and LOGXOR 
instructions. Instructions 21 and 23 use the PDL-POP address type, and instruction 20 uses the 
“constant” base register to get to a fixnum 2. Finally, instruction 22 uses the MOVEM 
instruction: the compiler wants to use the top value of tlic stack to store it into the value of x, 
but it doesn’t want to pop it off" the stack because it has another use for it: to return it from the 
function. 

Another four Qass II instructions implement some commonly used predicates: =, >, <, and 
EQ. Tlic two arguments come from the top of the stack and the specified address; the stack is 
popped, the predicate is applied to the two objects, and the result is left in the indicators so that 
a branch instruction can test it, and branch based on the result of tlic comparison. These 
instructions remove the top item on the stack and don’t put anything back, unlike the previous 
seL which put their results back on the stack. 

Next, there arc four Class II instructions to read, modify, and write a quantity in ways that 
are common in Lisp code, lliesc insuiictions are called SETE-CDR, SETE-CDDR, SETE-1+, 
and SETE-1-. The SETE- means to set the addressed value to tlic result of applying the 
specified one-argument function to the present value. For example, SETE-CDR means to read 
the value addressed, apply edr to it, and store the result back in the specified address. This is 
used when compiling (setq x (edr x)), which commonly occurs in loops; the other functions are 
used frequently in loops, too. 


;Y 

;X 

;X 
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I hcrc arc Uvu insiruclions used to bind special variables. The first is BIND-NIL, w'hich binds 
the cell addressed by the address field to nil; the second is BIND-POP, which binds tltc cell to 
an object popped off die stack rather titan nil. The latter instruction pops a value off tltc stack; 
the former docs not use tltc stack at all. 

There arc two instructions tt) store common values into addressed cells. SET-NIL stores nil 
into tltc cell specified by the address field; SET-ZERO stores 0. Neither instruction uses the 
stack at all. 

Finally, the PUSH-E instruction creates a locative pointer to the cell addressed by the 
specified address, and pushes it onto tltc stack. This is used in compiling {value-cell-location 
’z) where z is an argument or a local variable, rather titan a symbol (special variable). 

'Ihosc arc all of tltc Class 11 instructions. Here is a contrived example that uses some of the 
ones we haven’t seen, just to show you what they look like; 

(defun weird (x y) 

(cond ((= X y) 

(let ((♦foo'» nil) (♦bar* 5)) 

(declare (special •foo* *bar*)) 

(setq X (edr x))) 

nil) 

(t 

(setq X ni1) 

(caar (variable-location y))))) 

'The disassembled code looks like this: 


24 MOVE D-PDL ARG|0 iX 

25 = ARG|1 ;Y 

26 BR-NIL 35 

27 BIND-NIL FEF|6 :*F00* 

30 PUSH-NUMBER 5 

31 BIND-POP FEF|7 ;*BAR* 

32 SETE-CDR ARGIO ;X 

33 (MISC) UNBIND 2 bindings 

34 MOVE D-RETURN ’NIL 

35 SET-NIL ARG|0 ;X 

36 PUSH-E ARG|1 ;Y 

37 CAAR D-RETURN PDL-POP 


Instruction 25 is an = instruction; it numerically compares the top of the stack, x, with the 
addressed quantity, y. The x is popped off tlic stack, and the indicators arc set to the result of 
the equality test. Instruction 26 checks tlic indicators, branching to 35 if tlic result of the call to 
= was nil; tliat is, the machine will branch to 35 if the two values were not equal. Instruction 
27 binds *foo* to nil; instructions 30 and 31 bind * bar* to 5. Instruction 30 is a peculiar class 
IV instruction called PUSH-NUMBER which pushes a constant integer on the stack. ITie integer 
must be in the range of zero to 511 in order for PUSH-NUMBER to be used. Instruction 32 
demonstrates the use of SETE-CDR to compile (setq x (edr x)), and instruction 35 demonstrates 
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the use of SET-NIL to compile (setq x nil). Instruction 36 demonstrates the use of PUSH-E to 
compile (variable-location y). 

The Class III insimclions arc for branching. 'Hicsc have neitlicr addresses nor destinations of 
the usual sort. Instead, they have branch-addresses; they say where to branch, if the branch is 
going to happen. There arc several instructions, difi'ering in the conditions under which they 
branch and whether they pop the stack. Branch-addresses arc stored internally as self-relative 
addresses, to make Lisp Machine code rchKatablc, but the disassembler docs die addition for you 
and prints out T'Ll'-rclativc addresses so that you can easily see where the branch is going to. 

I'he branch instructions we have seen so far decide whether to branch on die basis of die nil- 
indicator, that is, whether the last value dealt with was nil or non-nil. BR-NIL branches if it was 
nil. and BR-NOT-NIL branches if it was not nil. riicrc arc two more instructions that test die 
result of die atom predicate on the last value dealt with. BR-ATOM branches if the value was 
an atom (that is. if it was anything besides a cons), and BR-NOT-ATOM branches if the value 
was not an atom (that is, if it was a cons). The BR instruction is an unconditional branch (it 
always branches). 

None of the above branching instiiictions deal with die stack. ITicrc arc two more 
instnictions called BR-NIL-POP and BR-NOT-NIL-POP, which arc die same as BR-NIL and 
BR-NOT-NIL except diat if die branch is not done, die top value on die stack is popped off the 
stack. These arc used for compiling and and or special forms. 

Finally, there are the Class IV instructions, most of which arc miscellaneous hand-microcoded 
Lisp functions. 'The fde SYS: SYS; DEFMIC LISP has a list of all the miscellaneous 
instructions. Most correspond to Lisp functions, including the subprimitives, although some of 
dicsc functions arc very low level internals that may not be documented anywhere (don’t be 
disappointed if you don't understand all of them). Please do not look at this file in hopes of 
finding obscure functions that you think you can use to speed up your programs; in fact, the 
compiler automatically uses these things when it can, and directly calling weird internal functions 
wilTonly serve to make your code hard to read, without making it any faster. In fact, we don’t 
guarantee that calling undcKumcntcd functions will continue to work in the future. 

The DEFMIC file can be useful for determining if a given function is in microcode, although 
the only definitive way to tell is to compile some code that uses it and look at the results, since 
sometimes the compiler converts a documented function with one name into an undocumented 
one with another name. 

31.4 Function Entry 

When a function is first entered in the Lisp Machine, interesting things can happen because 
of the features that are invoked by use of the various lambda-list keywords. I’he microcode 
performs various services when a function is entered, even before the first instruction of the 
function is executed. These services are called for by various fields of the header portion of the 
FEF, including a list called the Argument Descriptor List, or ADL. We won’t go into the 
detailed format of any of this, as it is complex and the details are not too interesting. 
Disassembling a function that makes use of the ADL prints a summary of what the ADL says to 
do, before the beginning of the code. 
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I’hc function-entry services include the initiali/ation of unsupplied optional arguments and of 
&AUX variables. I'he AHl. has a little instruction set of its own. and if the fomi that computes 
the initial value is something simple, such as a constant or a variable, then the ADI. can handle 
things itself. However, if tilings get too complicated, instructions arc needed, and tlic compiler 
generates some instructions at the front of tire function to initialize tlic unsupplied variables. In 
this case, the ADI. specifics several different starting addresses for die function, depending on 
which optional arguments have been supplied and which have been omitted. If all die optional 
arguments arc supplied, then the ADI, starts the function off after all the instructions diat would 
have initialized the optional arguments; since the arguments were supplied, dieir values should 
not be set, and so all dicsc instructions arc skipped over. Here's an example: 

(defvar ♦y*) 

(defun foo (ftoptional (x (car ♦y*)) (z (* x 3))) 

(cons X z)) 

The disassembled code looks like this: 

Arg 0 (X) is optional, local, 

initialized by the code up to pc 32. 

Arg 1 (Z) is optional, local, 

initialized by the code up to pc 35. 


30 CAR D-PDL FEF|6 ;*Y* 

31 POP ARG|0 :X 

32 MOVE D-PDL ARG|0 ;X 

33 * ’3 

34 POP ARG|1 ;Z 

35 MOVE D-PDL ARG|0 ;X 

36 MOVE D-PDL ARGIl ;Z 


37 (MISC) CONS D-RETURN 

If no arguments are supplied, the function will be started at instruction 30; if only one 
argument is supplied, it will be started at instruction 32; if both arguments are supplied, it will 
be started at instruction 35. 

The thing to keep in mind here is that when there is inidalization of variables, you may see 
it as code at die beginning of the function, or you may not, depending upon whether it is too 
complex for the ADL to handle. This is true of &aux variables as well as unsupplied &optional 
arguments. 

When there is a &rest argument, it is passed to the function as the zeroth local variable, 
radicr than as any of the arguments. This is not really so confusing as it might seem, since a 
Srest argument is not an argument passed by die caller; rather it is a list of some of the 
arguments, created by the function-entry microcode services. In any case the comment tells you 
what is going on. In fact, one hardly ever looks much at the address fields in disassembled code, 
since die comment tells you die right thing anyway. Here is a silly example of die use of a &rest 
argument: 
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(defun prod (&nest values) 

(apply #’♦ values)) 

The disjjssemblcd code looks like this: 

20 MOVE D-PDL FEf|6 •,#'* 

21 MOVE D-PDL LOCAL|0 ;VALUES 

22 (MISC) APPLY D-RETURN 

As can be seen, values is referred to as LOCAL|0. 

Another thing the mierwode docs at function entry is to bind the values of any arguments or 
"&aux variables that arc special. Thus, you won’t see any BIND instructions for binding Utcin. 


31.5 Special Class IV Instructions 

We said earlier tliat most of the Class IV instructions arc miscellaneous hand-micrrxodcd Lisp 
functions. However, a few of tlicm arc not Lisp functions at all. There arc two insuuctions that 
arc printed as UNBIND 3 bindings or POP 7 values: tlic number can be anything up to 16 
(these numbers arc printed in decimal). I'hcsc instructions just do what they say, unbinding the 
last n values tliat were bound or popping the top n values off the stack. 

Another Class IV instniction is PUSH-NUMBER. It pushes a constant integer, in the range 
zero to 511. An example of it appeared on page 760. 

The array referencing functions—aref, aset, and aloe—take a variable number of arguments, 
but they are handled differently depending on how many there are. For one-, two-, and three- 
dimensional arrays, tliese functions arc turned into internal functions with names ar-1, as-1, and 
ap-1 (with the number of dimensions substituted for 1). Again, there is no point in using these 
functions yourself; it would only make your code harder to understand but not any faster at all. 
When there are more than three dimensions, the functions aref, aset and aloe are called in the 
ordinary manner. 


(defun foo (y x i j &aux v) 
(setq V (aref x i j)) 
(setf (aref y i) v)) 


16 

MOVE D-PDL ARG|1 

;X 

17 

MOVE D-PDL ARGj2 

:I 

20 

21 

MOVE D-PDL ARG|3 
(MISC) AR-2 D-PDL 

;J 

22 

POP LOCAL|0 

:V 

23 

MOVE D-PDL ARG|0 

;Y 

24 

MOVE D-PDL ARGi2 

;I 

25 

26 

MOVE D-PDL LOCAL|0 
(MISC) SET-AR-1 D-RETURN 

;V 
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Reference to one-dimensional arrays with constant subscripts use special instructions w'hich 
have the array index encoded instead of an address. 

(defun foo (x) 

(+ (aref x 3) (array-leader x 2)) 

(self (aref x 5) t)J 

FOO: 

16 MOVE D-PDL ARG|0 ;X 

17 AR-1 (3) D-I6N0RE 

20 MOVE D-PDL ARG|0 ;X 

21 ARRAY-LEADER (2) D-IGNORE 

22 MOVE D-PDL ARG|0 ;X 

23 MOVE D-PDL ‘T 

24 SET-AR-1 (5) D-RETURN 

'I'hc AR-1 instruction is to be distinguished from tlic MISC AR-1 instniction. AR-1 pops an 
array off tlic stack and encodes tlic subscript itself, llic 3 in (3) is the subscript. ARRAY- 
LEADER is similar but refers to an array leader slot. SET-AR-1 pops an array and then pops a 
value to store into it at the specified slot. SET-AR-1 is analogous. There also exist 
%tNSTANCE-REF and SET-%INSTANCE-REF instructions. 

When you call a function and expect to get more than one value back, a slightly different 
kind of function calling is used. Here is an example tliat uses multiple-value to get two values 
back from a function call: 

(defun foo (x) 

(let (y z) 

(multiple-value (y z) 

(bar 3)) 

(+ X y z))) 

The disassembled code looks like this: 


20 MOVE D-PDL FEF16 ;#’BAR 

21 MOVE D-PDL *2 

22 (MISC) XCALL-MULT-VALUE D-IGNORE 

23 MOVE D-LAST ’3 

24 POP LOCAL 11 ;Z 

25 POP LOCALjO ;Y 

26 MOVE D-PDL ARG|0 ;X 

27 -r LOCALjO ;Y 

30 + LOCAL 11 ;Z 

31 MOVE D-RETURN PDL-POP 


A %CALL-MULT-VALUE instruction is used instead of a CALL instruction. The destination 
field of %CALL-MULT-VALUE is unused and will always be D-IGNORE. %CALL-MULT- 
VALUE Uikcs two “arguments”, which it finds on tlic stack; it pops botli of them, 'fhe first one 
is the function object to be applied; tlic second is the number of return values that arc expected. 
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The rest of the call proceeds as usual, but when tlie call returns, the returned values are leh on 
the stack. Hie number of objects left on the stack is always the same as die second “argument'’ 
to %CALL-MULT-\/ALUE. In our example, the two values returned are left on tlie stack, and 
they are immediately popped off into z and y. There is also a %CALLO-MULT-VALUE 
instruction, for die same reason CALLO exists. 

The multiple-value-bind form works similarly: here is an example: 

(defun foo (x) 

(muHiple-value-bind (y *foo* z) 

(bar 3) 

(declare (special *foo*)) 

(+ X y z))) 

The disassembled code looks like this: 


22 MOVE D-PDL FEF|7 ;J’BAR 

23 MOVE D-PDL ’3 

24 (MISC) “/.CALL-MULT-VALUE D-IGNORE 

25 MOVE D-LAST ’3 

26 POP LOCAL 11 ;Z 

27 BIND-POP FEF|6 ;*F00* 

30 POP LOCAL|0 ' ;Y 

31 MOVE D-PDL ARG|0 ;X 

32 + LOCALjO ;Y 

33 + LOCAL 11 ;Z 

34 MOVE D-RETURN PDL-POP 


The %CALL-MULT-VALUE instruction is sdll used, leaving the results on the stack; these 
results are used to bind the variables. 

Calls done with multiple-value-list work with the %CALL-MULT-VALUE-LIST instruction. 
It takes one “argument” on the stack: the ftinction object to apply. When the function returns, 
the list of values is left on the top of the stack. Here is an example: 

(defun foo (x y) 

(multiple-value-list (bar -7 y x))) 

The disassembled code looks like this: 

22 MOVE D-PDL FEF|6 ;#’BAR 

23 (MISC) %CALL-MULT-VALUE-LIST D-IGNORE 

24 MOVE D-PDL FEF|7 ;’-7 

25 MOVE D-PDL ARG|1 ;Y 

26 MOVE D-LAST ARG|0 ;X 

27 MOVE D-RETURN PDL-POP 

Returning of more than one value from a function is handled by special miscellaneous 
instructions. ^RETURN-2 and %RETURN-3 are used to return two or three values; these 


PS:<L.MAN>COI)E.'rKXT.36 


8-JUN-84 



Spcciiil Class IV' Iiislriictions 


766 


l.isp Machine Manual 


insiructions take two and three arguments, respectively, on the stack and return from tlic current 
function just as storing to D-RETURN would. If there arc more than Uircc return values, they 
arc all pushed, then the number tliat there were is pushed, and tlien the %RETURN-N 
instruction is executed. None of these instructions use their destination field. Note: die return- 
list function is just an ordinary miscellaneous instruction; it takes the list of values to return as an 
argument on the stack and returns those values from the current function. 


The function apply is compiled using a special instruction called %SPREAD to iterate over 
tlic elements of its last argument, which should be a list. %SPREAD takes one argument (on the 
stack), which is a list of values to be passed as arguments (pushed on die sutek). If die 
destination of %SPREAD is D-PDL (or D-NEXT), then the values arc just pushed; if it is D- 
LAST, then after the values arc pushed, the function is invoked, apply with more than two 
arguments will always compile using a %SPREAD whose destination is D-LAST. Here is an 
example: 

(defun foo (a b &rest c) 

(apply ^’format t a c) 
b) 

'i'hc disassembled code looks like this: 


FOO: 

20 CALL D-IGNORE FEF|6 

21 MOVE D-PDL ’T 

22 MOVE D-PDL ARG|0 

23 MOVE D-PDL LOCAL|0 

24 (MISC) ^SPREAD D-LAST 

25 MOVE D-RETURN ARG|1 


FORMAT 

;A 

;C 

:B 


Note that in instruction 23, the address LOCAL|0 is used to access the &rest argument. 

The catch special form is also handled specially by the compiler. Here is a simple example 
of catch; 

(defun a 0 

(catch ’foo (bar))) 

The disassembled code looks like this: 

24 MOVE D-PDL FEF|6 ;’30 

25 (MISC) ZCATCH-OPEN D-RETURN 

26 MOVE D-PDL FEF|7 ;’FOO 

27 CALLO D-RETURN FEF|8 ;#’BAR 

The %CATCH-OPEN instruction is like the CALL instruction: it starts a call to the catch 
fiinction. It takes one “argument” on the stack, which is the location in the program that should 
be branched to if this catch is thrown to. In addition to saving that program location, the 
instruction saves the state of the su»ck and of special-variable binding so that they can be restored 
in the event of a throw. So instructions 24 and 25 start a catch block, and the rest of the 
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function computes tlic two arguments of the catch. Note, however, that catch is not actually 
called. The last form inside the catch, in this ease (bar), is compiled so as to return its values 
directly out of the function a. The only way tliat the inactive suick frame for catch matters is if 
a throw is done during the execution of bar. This searches for a pending call to catch and 
returns from tliat frame. In tliis case, since the %CATGH-OPEN instruction specifics D- 
RETURN. the values tlirown arc returned from a. 

You may have wondered why instaiction 24 is there at all. If the destination of a catch is 
not D-RETURN, it is necessary for throw to resume execution of tlic function containing the 
catch. Then it is ncccss;iry to specify what instruction to resume at. For example; 

(defun a () 

(catch ’foo (bar)) 

(print t)) 

The disassembled code looks like this: 


26 MOVE D-PDL FEF|6 ;’32 

27 (MISC) XCATCH-OPEN D-IGNORE 

30 MOVE D-PDL FEF|7 ;’(BAR) 

31 MOVE D-LAST FEF|8 ;’FOO 

32 CALL D-RETURN FEF|9 ;i5'’PRINT 


33 MOVE D-LAST ’T 

The instruction 26 pushes 32, which is the number of instruction at which execution should 
resume if tlicre is a throw. 

To allow compilation of (multiple-value (...) (catch ...)), there is a special instruction called 
%CATCH-OPEN-MULT-VALUE, which is a cross between %CATCH-OPEN and %CALL- 
MULT-VALUE. 
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32. Querying the User 

The following functions provide a convenient and consistent interface for asking questions of 
the user. Questions arc printed and the answers arc read on the stream *query-io*, which 
normally is synonymous with *terminal-io* but can be rebound to another stream for special 
applications. 

fhe macro with-timeout (see page 686) can be used with the functions in this chapter to 
assume an answer if die user docs not respond in a fixed period of time. 

We first describe two simple functions for yes-or-no questions, tlicn tlic more general function 
on which all querying is built. 

y-or-n-p &optional formaf-siring &rcst fonnat-args 

This is used for asking the user a question whose answer is cither ‘y’ for ‘yes’ or ‘n’ for 
‘no’. It prints a message by passing formal-string and format-args to format, reads a one- 
character answer, echoes it as ‘Yes' or ‘No’, and returns t if the answer is ‘yes’ or nil if 
the answer is ‘no’. I'hc characters which mean ‘yes’ arc ‘Y’, “1”, Space, and Hand-up. 
ITie characters w'hich mean "no" arc ‘N’, Rubout, and Hand-down. If any other 
character is typed, the hinction beeps and demands a ‘Y or N’ answer. 

You should include a question mark and a space at the end of the message, y-or-n-p 
does type ‘(Y or N)’ for you. 

*query-io* is used for all input and output. 

y-or-n-p should be used only for questions that tire user knows are coming. If the user 
is not going to be anticipating the question (c.g. if the question is ‘‘Do you really want to 
delete all of your files?’’ out of the blue) then y-or-n-p should not be used, because the 
user might type ahead a ‘1’’, ‘Y’, ‘N’, Space, or Rubout, and therefore accidentally 
answer tire question. In such eases, use yes-or-no-p, 

yes-or-no-p &optional formal-string tost format-args 

This is used for asking die user a question whose answer is either ‘yes’ or ‘no’. It prints a 
message by passing format-string and fonnat-args to format, beeps, and reads in a line 
from *query-io*. If the line is ‘yes’, it returns t. If the line is ‘no’, it returns nil, 
(Case is ignored, as arc leading and trailing spaces and tabs.) If the input line is anything 
else, yes-or-no-p beeps and demands a ‘yes or no’ answer. 

You should include a question mark and a space at the end of the message, yes-or-no- 
p does type ‘(Yes or No)’ for you. 

“query-io* is used for all input and output 

To allow the user to answer a yes-or-no question with a single character, use y-or-n-p. 
yes-or-no-p should be used for unanticipated or momentous questions; this is why it 
beeps and why it requires several keystrokes to answer it 
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fquery options format-slrina &rcst fonnal-args v j , 

Asks a question, primed by (format *query-io* format-string fonnat-args...). and rctuins 
die answer, fquery takes care of checking for valid answers, reprinting the question when 
the user clears the screen, giving help, and so forth. 


options is a list of alternating keywords and values, used to select among a variety of 
features. Most callers p;tss a constant list as the options (rather dian consing up a list 
whose contents varies). Hie keywords allowed arc: 

;type What type of answer is expected. I'hc currently-defined types arc :tyi (a 

single character), ireadline or :mini-buffer-or-readline (a line tenninated 
by a carriage return). :tyi is tlic default, -.mini-buffer-or-readline is 
nearly tlie same as :readline, tlic only difference being tliat the former 
uses a minibuffer if used inside die editor. 


•.choices Defines die allowed answers. The allowed forms of choices are 
complicated and explained below, fhe default is die same set of choices 
as die y-or-n-p function (see above). Note that die :type and ichoices 
• options should be consistent with each other. 

:list-choices If t, the allowed choices are listed (in parcndicscs) after the quesdon. 'I’hc 
default is t; supplying nil causes die choices not to be listed unless the 
user tries to give an answer which is not one of die allowed choices. 

:help-function Specifics a function to be called if the user hits the Help key. The default 
help-function simply lists die available choices. Specifying nil disables 
special treatment of Help. Specifying a function of diree arguments—the 
stream, the list of choices, and the type-function—allows smarter help 
processing. The type-function is the internal form of the :type option and 
can usually be ignored. 

•.condition If non-nil, a signal name (see page 713) to be signaled before asking the 
question. A condition handler may handle the condition, specifying an 
answer for fquery to return, in which ease the user is not asked. The 
details arc given below. The default signal name is :fquery, which signals 
condition name ifquery. 


:fresh-line 


:beep 


:stream 


:clear-input 


If t, *query-io* is advanced to a fresh line before asking the question. If 
nil,’ the question is printed wherever the cursor was left by previous 
typeouL The default is t. 

If t. fquery beeps to attract the user’s attention to the question. The 
default is nil, which means not to beep unless the user tries to give an 
answer which is hot one of the allowed choices. 

The value should be either an I/O stream or a symbol or expression that 
will evaluate to one. fquery uses the specified stream instead of *query- 
io* for all its input and output. 

If t, fquery throws away type-ahead before reading the users response to 
the question. Use this for unexpected questions. I’hc default is nil, which 
means not to throw away type-ahead unless the user tries to give an 
answer which is not one of the allowed choices. In that case, type-ahead 
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is discarded since the user probably wasn't expecting the question. 

:make-complete 

If t and *query-io* is a typeout-window, tlic window is “made complete” 
after die question has been answered. This tells die system that the 
contents of the window arc no longer useful. Refer to die window system 
dcK'umentation for further explanation. The default is t. 

The argument to the :choices option is a list eaeh of whose elements is a choice, fhe 
edr of a clioice is a list of the user inputs which correspond to diat choice. 'I'licse should 
be characters for :type :tyi or strings for :type :readline. 'Lhe car of a choice is either a 
symbol which fquery should return if the user answers with that choice, or a list whose 
first element is such a symbol and whose second element is die string to be echoed when 
die user selects the choice. In the foniier case nothing is echoed. In most eases :type 
deadline would use the first format, since the user’s input has already been echoed, and 
•type ;tyi would use the second format, since the input has, not been echoed and 
furthermore is a single character, which would not be mnemonic to see on the display. 

A choice can also be the symbol ;any. If used, it must be the last choice. It means that 
any input is allowed, and should simply be returned as a string or character if it docs not 
match any of the other choices. 

Perhaps this can be clarified by example. 'Fhe yes-or-no-p function uses this list of 
choices: 

({t "Yes") (nil "No")) 
and the y-or-n-p function uses this list; 

(({t "Yes.") #\y At #\space Ahand-up) 

{(nil "No.") #\n #\rubout #\hand-down)) 

If a signal name is specified (or allowed to default to :fquery), before asking the question 
fquery will signal it. (See section 30.1, page 698 for information about conditions.) 
make-condition will receive, in addition to the signal name, all the arguments given to 
fquery, including the list of options, the format string, and all the format arguments, 
fquery provides one proceed type, :new-value, and if a condition handler proceeds, the 
argument it proceeds witli is returned by fquery. 

If you want to use the formatted output functions instead of format to produce the 
promting message, write 

(fquery options {format:outfmt exp-orsiring exp-or^siring .,.)) 
format:outfmt puts the output into a list of a string, which makes format print it exactly 
as is. 'ITicrc is no need to supply additional arguments to the fquery unless it signals a 
condition. In that case the arguments might be passed so that the condition handler can 
see them. I’hc condition handler will receive a list containing one string, the message, as 
its third argument instead of just a string. If this argument is passed along to format, all 
the right things happen. 
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fquery (condition) 


Condition 


Iliis condition is signaled, by default, by fquery. The condition instance supports tltesc 
operations: 

:options Returns tltc list of options given to fquery, 

:format-string Returns the format string given to fquery, 

:format-args Returns the list of additional args for format, given to fquery. 

One proceed type is provided, :new-value. It should be used with a single argument, 
which will be returned by fquery in lieuc of asking the user. 

format ry-or-n-p-optlons Constant 

A suitable list to pass as the first argument to fquery to make it behave like y-or-n-p. 

format :yos-or-no-p-opt1ons Constant 

A suitable list to pass as tlic first argument to fquery to make it behave like yes-or-no- 
p. 

format :y-or-n-p-cho1C8S Constant 

A list which y-or-n-p uses as tlie value of the :choices option. 
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33. Initializations 

There arc a number of programs and facilities in the I-isp Machine lltat require tliat 
“initialization routines” be run either when tlic facility is first loaded, or when the system is 
booted, or both. These inititilization routines may, set up data structures, start processes running, 
open network connections, and so on. 

It is easy to perform an action when a file is loaded: simply place an expression to perform 
the action in tlic file. But this causes the action to be repeated if tltc file is lottdcd a second time, 
and often tliat should not be done. Also, tliis docs not provide a way to cause actions to be 
taken at other times, such as when the system is booted or when a garbage collection is started. 

The miiializatian lisi facility serves these needs. An initialization list is a symbol whose value 
is a list of iiiilializalioiis. ptit on by various programs, all to be perfonned when a certain event 
(such as a cold boot) happens. When tlic event occurs, the system function in charge of handling 
the event {si:lisp-reinitialize, for cold boot) executes all the initializations on die appropriate list, 
in the order they arc present on die list. 

iittch initialization has a name, a form to be evaluated, a flag saying whether the form has 
yet been evaluated, and the source file of the initialization, if any. The name is a string or a 
symbol and lies in the car of an initializadon; thus assoc may be used on initialization lists to 
find particular initializations. 

System and user files place initializations on initializadon lists using die function add- 
initialization . The name of the initialization is specified so diat die system can distinguish 
between adding a new initialization and repeating or changing die definition of an inidalizadon 
already known: if dicre is already an inidalizadon with the specified name, this is a new 
definition of the same inidalizadon. One can specify that die initializadon be executed 
immediately if it is new but not if it is repeated. 

User programs arc free to create their own inidalizadon lists to be run at their own dmes. 

33.1 System Initialization Lists 

'There arc several initialization lists built into the system. Each one is invoked by the system 
at a specific time, such as immediately after a cold boot, or during disk-save. A user program 
can put initializations on dicse lists to cause actions to be taken at those dmes as die program 
needs. This avoids the need to modify system ftincdons such as lisp-reinitialize or disk-save in 
order to make them interact properly widi the user program. 

The system initialization lists arc generally identified by keywords rather than by their actual 
names. We name them here by their keywords. In each case, the actual inidalizadon list symbol 
is in die si package, and its name is die conventional keyword followed by ‘-inidali/.ation-list’.^ 
Thus, for :cold, there is si:cold-initialization-list. This is just a convention. 
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Unless olhcrwisc specified, an initialization added to a system list is not run when it is added, 
only when the appropriate event happens. A few system lists tire exceptions and also run each 
initialization when it is added. Such exceptions arc noted explicitly. 

'I’hc :once initialization list is used for initializations that need to be done only once when tlie 
subsystem is loaded and must never be done again. For example, there arc some databases that 
need to be initialized tite first time the subsystem is loaded, but should not be reinitialized every 
time a new version of the software is loaded into a currently running system. 'ITiis list is for Uiat 
purpose. When a new initialization is added to this list, it is executed immediately; but when an 
initialization is redefined, it is not executed again. 

I'he :coid initialization list is used for things that must be run once at cold-boot time. The 
initializations on this list arc run after die ones on :system but before die ones on die :warm list. 

The :warm initialization list is used for diings which must be run every time the machine is 
booted, including wann boots. The function diat prints the greeting, for example, is on diis list. 
For cold boots, the :cold initializations arc done before die :warm ones. 

The :system initialization list is like die :warm list but its initializations arc run before diose 
of die :cold list. These arc generally very fundamental system initializations that must be done 
before die :cold or ;warm initializations can work. Initializing die priKCss and window systems, 
the file system, and die Chaosnet NCP falls in diis category. By default, a new initialization 
added to this list is run immediately also. In general, the system list should not be touched by 
user subsystems, though dierc may be eases when it is necessary to do so. 

llie :before-cold initialization list is used for things to be run by disk-save. Thus they 
happen essentially at cold boot dmc, but only once when the world is saved, not each time it is 
started up. 

ITic :site initialization list is run every time a new site table and host table are loaded by 
update-site-configuration-info. By default, adding an initialization to this list runs the 
inidalization immediately, even if the initialization is not new. 

The :site-option initialization list is run every time the site options may have changed; that 
is, when a new site tables are loaded or after a cold boot (to sec the per-machine options of the 
machine being booted on). By default, adding an initialization to this list runs the initialization 
immediately, even if the initialization is not new. 

The :full-gc initialization list is run by the function si:full-gc just before garbage collecting. 
Initializations might be put on this list to discard pointers to bulky objects, or to turn copy lists 
into cdr-coded form so that they will remain permanently localized. 

ITie :after-flip initialization list is run after every garbage collection flip, at the beginning of 
scavenging. These initiali7.ations can force various objects to be copied into new space near each 
other simply by referencing them all consecutively. 

The :after-full-gc initialization list is run by the function si:full-gc just after a flip is done, 
but before scavenging. 
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I'hc :iogin and ilogout lists arc run by die login and logout functions (see page 801) 
respectively. Note that disk-save calls logout. Also note that often people don’t call logout; 
they jtist cold-boot Hie machine. 

33.2 Programming Iniliaiizations 

add-1n1t1a11zation nawe fonn &optional Usi-of-keywords uiitialization-Ust-mme 

Adds an initialization called name with the fonn form to the initialization list specified 
either by iniiialization-lisl-name or by keyword. If the initialization list already contains an 
initialization called name, it is redefined to execute form. 

inilialization-lisl-name, if specified, is a symbol that has as its value the initialization list. 
If it is void, it is initialized (!) to nil, and is given a si:initialization-list property of t. If 
a keyword specifies an initialization list, initializalion-lisl-name is ignored and should not 
be specified. 

The keywords allowed in list-of keywords are of two kinds. Most speeify the initialization 
list to use; a list of such keywords makes up most of the previous section. Aside from 
them, fotir other keywords are allowed, which specify when to evaluate form. ITicy are 
called the when-keywords. Here is what tlicy mean: 

:normal Only place the form on the list. Do not evaluate it until the time comes 
to do this kind of initialization. 'Fhis is the default unless :system, :once, 
:site or :site-option is specified. 

:first Evaluate the form now if it is not flagged as having been evaluated 

before. This is the default if :system or :once is specified. 

:now Evaluate the form now unconditionally as well as adding it to the list 

:redo Do not evaluate the form now, but set the flag to nil even if the 

initialization is already in the list and flagged t. 

Actually, the keywords are compared with string-equal and may be in any package. If 
both kinds of keywords are used, the list keyword should come before the when-keyword 
in list-of-keywords', otherwise the list keyword may override the when-keyword. 

The add-initialization function keeps each list ordered so that initializations added first 
arc at tlic front of the list llierefore, by controlling the order of execution of the 
additions, you can control explicit dependencies on order of initialization. Typically, the 
order of additions is controlled by die loading order of files. The system list is the most 
critically ordered of the predefined lists. 

The add-initialization keywords that specify an initialization list are defined by a variable; 
you can add new keywords to it. 
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34.1 Gclting and Setting the Time 

get-decoded-tlme 

t1me:get-t1me 

Gets the current time, in decoded form. Return seconds, minutes, hours, date, month, 
year, day-of-thc-wcek, and daylight-savings-time-p, with the same meanings as decode- 
universal-time (sec page 782). If die current time is not known, nil is returned. 

The name time:get-time is obsolete. 

get-un 1 v 0 rsal-tlme 

Returns the current time in Universal Time form. 

time:set-local-time &optional iiewiime 

Sets the local time to iiew-imie. If new’-iime is supplied, it must be cither a universal 
time or a suitable argument to time:parse-universal-time (sec page 781). If it is not 
supplied, or if there is an error parsing the argument, you arc prompted for tlie new 
time. Note that you will not normally need to call this function; it is useful mainly when 
the timebase gets screwed up for one reason or another. 

34.1.1 Elapsed Time in 60ths of a Second 

The following Rinctions deal with a different kind of time. These arc not calendrical 
date/times, but simply elapsed time in 60ths of a second. These times arc used for many internal 
purposes where die idea is to measure a small interval accurately, not to depend on the dme of 
day or day of month. 

time 

Returns a number that increases by 1 every 60th of a second. 'Fhe value wraps around 
roughly once a day. Use the time-lessp and time-difference ametions to avoid getting 
in trouble due to the wrap-around, time is completely incompatible with the Maclisp 
function of the same name. 

Note that time with an argument measures the length of dme required to evaluate a form. 
Sec page 794. 

get-Internal-run-time 
get-Internal-real-time 

Returns the total time in 60ths of a second since the last boot. Tliis value docs not wrap 
around. Eventually it becomes a bignum. The Lisp Machine does not disdnguish between 
run dme and real dme. 

Internal-time-units-per-second Constant 

According to Common Lisp, this is the rado between a second and the time unit used by 
values of get-internal-real-time. On the Lisp Machine, the value is 60. The value may 
be different in other Common Lisp implementadons. 
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t1me-1essp limcl time} 

t if time! is earlier than compensating for wrap-around, otherwise nil. 
time-difference litiwl iime2 

Assuming time! is later than time2, returns the number of 60ths of a second dilFcrcncc 
between tliem, compensiiting for wrap-around. 

time-increment lime huerval 

Increments lime by inierval, wrapping around if appropriate. 

34.1.2 Elapsed Time in Microseconds 

time:microsecond-t1me 

Returns the value of tlic microsecond timer, as a bignum. ITie values returned by this 
function wrap around back to zero about once per hour. 

time:fixnum-microsecond-tiroe 

Returns as a fixnum the value of the low 23 bits of the microsecond timer. ITiis is like 
time:microsecond-time, with the advantage that it returns a value in the same fonnat as 
the time function, except in microseconds ratlier dian 60ths of a second. ITiis means that 
you can compare fixnum-microsecond-timcs with time-lessp and time-difference. 
time:fixnum-microsecond-time is also a bit faster, but has the disadvantage that since 
you only sec the low bits of tlie clock, the value can wrap around more quickly (about 
every eight seconds). Note that the Lisp Machine garbage collector is so designed that the 
bignums produced by time:microsecond-time arc garbage-collected quickly and efficiently, 
so the overhead for creating the bignums is really not high. 


34.2 Printing Dates and Times 


3'hc functions in this section create printed representations of times and dates in various 
fonnats and send the characters to a stream. To any of these functions, you may pass nit as the 
stream parameter and the function will return a string containing the printed representation of the 
time, instead of printing the characters to any stream. 

'Flic three functions time:print-time, time:print-universal-time, time:print-brief-universal- 
time and time:print-current-time accept an argument called dale-print-mode, whose purpose is to 
control how the date is printed. It always defaults to the value of time:’default-date-print¬ 
mode*. Possible values include: 


:dd//mm//yy 

;mm//dd//yy 

:dd-mm-yy 

:dd-mmm-yy 

:|dd mmm yy] 

:ddmmmyy 


Print the date as in ‘3/16/53’. 
Print as in ‘16/3/53’. 

Print as in ‘16-3-53’. 

Print as in ‘16-Mar-53’. 

Print as in ‘16 Mar 53’. 

Print as in ‘16Mar53’. 
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ryymmdd Print as in ‘530316’. 

:yymmmdd Print as in ‘53Marl6’. 

t 1 me:pr 1 nt-current-t 1 m 0 ifeopiional (s/rem//‘standard-output*) 

Prints tlic current time, formatted as in 11/25/80 14:50:02, to tlic specified stream. The 
date portion may be printed differently according to the argument dnte-prhihmode. 

time;print-time seconds minutes hours dale month year &optional 
(stream ‘standard-output*) date-print-mode 

Prints die specified lime, formatted as in 11/25/80 14:50:02, to die specified stream. 
The date portion may be printed differently according to the argument dale-print-mode. 

t1me;pr1nt-un1versal-t1me universal-lime &optional (sv/wt/n‘standard-output*) 
{///;!czo/;rtime:*timezone‘) date-print-mode 

Prints the specified time, fonnatted as in 11/25/80 14:50:02, to the specified stream. 
Tlic date portion may be printed differently according to the argument date-print-mode. 

t1me;pp1nt-br1ef-un1versal-t1me universal-time &optional (i/remn‘standard-output*) 
reference-time dale-print-mode 

This is like time:print-universal-time except diat it omits seconds and only prints those 
parts of universal-lime that differ from reference-time, a universal time that defaults to the 
current time. I'hus die output is in one of the following three forms: 

02:59 ; the same day 

3/414:01 ;a different day in the same year 

8/17/74 15:30 ; a different year 

'fhe date portion may be printed differently according to the argument date-print-mode. 

t1me:*default-dat0-pr1nt-mode* Variable 

Holds the default for the date-print-mode argument to each of the functions above. 
Initially the value here is :mm//dd/yy. 

timeiprint-current-date &opdonal (s/reow‘standard-output*) 

Prints the current time, formatted as in Tuesday the twenty-fifth of November, 1980; 
3:50:41 pm, to the specified stream. 

t1me:pr1nt-date seconds minutes hours date month year day-of-the-week &optional 
(s/reaw‘standard-output*) 

Prints the specified time, formatted as in Tuesday the twenty-fifth of November, 1980; 
3:50:41 pm, to the specified stream. 

time: print-universal-date universal-time &optional (s/rea/n‘standard-output*) 

time:‘timezone*) 

Prints tlie specified time, formatted as in Tuesday the twenty-fifth of November, 1980; 
3:50:41 pm, to the specified stream. 
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34.3 Reading Dales and TImes 

These functions accept most reasonable printed representations of date and time and convert 
tliem to the standard internal fonns. The following arc representative formtits that arc accepted by 
tlic parser. Note that slashes arc cscitpcd with additional slashes, as is necessary if these strings 
arc input in traditional syntax. 

"March 15. 1960" "3//15//60" "3//15//1960" 

"15 March 1960" "15//3//60" "15//3//1960" 

"March-15-60" "3-15-60" "3-15-1960" 

"15-March-60" "15-3-60" "15-3-1960" 

"15-Mar-60" "3-15" "15 March 60" 

"Fifteen March 60" "The Fifteenth of March, I960;" 

"Friday, March 15, 1980" 

"1130." "11:30" "11:30:17" "11:30 pm" 

"11:30 AM" "1130" "113000" 

"11.30" "11.30.00" "11.3" "11 pm" 

"12 noon" "midnight" "m" "6:00 gmt" "3:00 pdt" 

any date format may be used with any time format 

"One minute after March 3, 1960" 
meaning one minute after midnight 
"Two days after March 3, 1960" 

"Three minutes after 23:59:59 Dec 31, 1959" 

"Now" "Today" "Yesterday" "five days ago" 

"two days after tomorrow" "the day after tomorrow" 

"one day before yesterday" "BOBOOZ’s birthday" 

time:parse string &optional (s/or/0) (e/tt/nil) (futurept) base-time must-have-time 
date-must-have-year time-must-have-second (day-must-be-valid t) 

Interpret string as a date and/or time, and return seconds, minutes, hours, date, month, 
year, day-of-thc-week, daylight-savings-time-p, and relativc-p. start and end delimit a 
substring of the string; if end is nil, the end of the string is used, must-have-time means 
that string must not be empty, date-must-have-year means that a year must be explicitly 
specified, time-must-have-second means that tlie second must be specified. daymUst-be- 
valid means that if a day of the week is given, then it must actually be the day that 
corresponds to the date, base-time provides the defaults for unspecified components; if it 
is nil, tlic current time is used, futurep means that tlic time should be interpreted as 
being in the future; for example, if tlic base time is 5:00 and the string refers to the 
time 3:00, lliat means the next day if juturep is non-nil, but it means two hours ago if 
futurep is nil. The relative-p returned value is t if the string included a relative part, such 
as ‘one minute after’ or ‘two days before’ or ‘tomorrow’ or ‘now’; otherwise, it is nil. 
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ir the input is not valid, the error condition sys:parse-error is signaled (see page 505). 

t1me:parse-un1vers8T-time siring &()ptional (slanO) (m/nil) (Jhiurept) base-lime 

musl-have-lime dale-niusl-have-year Ume-mush have-second (da}^musl-be-valid t) 
This is the same as time:parse except that it returns tw'o values: an integer, representing 
tlic time in Univcrsiil Time, and the relalive-p value. 

34.4 Reading and Printing l ime Intervals 

In addition to the functions for reading and printing instants of time, there are other 
functions specifically for printing time intervals. A time interval is cither a number (measured in 
seconds) or nil. meaning ‘never’. The printed representations used look like ‘3 minutes 23 
seconds’ for actual intervals, or ‘Never’ for nil (some other synonyms and abbreviations for ‘never’ 
arc accepted as input). 

tlmerprlnt-lnterval-or-never imerval &optional (s/zram‘standard-output*) 

inierval should be a non-negative fixnum or nil. Its printed representation as a time 
interval is written onto stream. 

t 1 m 0 :parse- 1 nterva 1 -or-nevep string &optional start end 

Converts string, a printed representation for a time interval, into a number or nil. start 
and end may be used to specify a portion of siring to be used; die default is to use all of 
string. It is an error if the contents of string do not look like a reasonable time interval. 
Here are some examples of acceptable strings: 

"4 seconds" "4 secs" "4 s" 

"5 mins 23 secs" "5 m 23 s" "23 SECONDS 5 M" 

"3 yrs 1 week 1 hr 2 mins 1 sec" 

"never" "not ever" "no" "" 

Note diat several abbreviations are understood, the components may be in any order, and 
case (upper versus lower) is ignored. Also, “months” are not recognized, since various 
months have different lengths and there is no way to know which month is being spoken 
of. lliis function always accepts anything that was produced by time:print-interval-or- 
never; furthermore, it returns exacUy the same fixnum (or nil) that was printed. 

tlmetread-interval-or-never &optional (s/rcam*standard-input*) 

Reads a line of input from stream (using readline) and then calls time:parse-interval-or- 
never on the resulting string. 


PS:<I..MAN>TIME.TEXT.40 


8-JUN-84 



l ime Conversions 


782 


Lisp Machine Manual 


34.5 rime Conversions 

decod8-un1versa1-t1me universal-tiwe &optional (//»/<’zo/;<’time:*timezone*) 

Converts universal-lime into its decoded representation. I'hc following values arc returned: 
seconds, minutes, hours, date, month, year, day-of-tlie-week, daylight-savings-time-p. and 
the time/.one used, daylight-savings-time-p tells you whether or not daylight savings time is 
in effect; if so, die value of hour has been adjusted accordingly. You can specify 
limezune explicitly if you want to know the equivalent representation for this time in other 
parts of tlie world. 

encode-universal-time seconds minutes hours date month year &optional limezone 

Converts die decoded time into Universal Time format, and return the Universal Time as 
an integer. If you don't specify limezone, it defaults to the current time/.one adjusted for 
daylight savings time: if you provide it explicitly, it is not adjusted for daylight savings 
time. If year is less dian 100, it is shifted by centuries until it is within 50 years of the 
present. 

t1me:*t1mezone* Variable 

The value of time:*timezone* is the dme zone in which this Lisp Machine resides, 
expressed in terms of the number of hours west of GMl’ this time zone is. I’his value 
does not change to reflect daylight savings dme; it tells you about standard time in your 
part of the world. 

34.6 Internal Functions 

These functions provide support for those listed above. Some user programs may need to call 

them direedy, so they are documented here. 

time: Initial Ize-tlinebase 

Initializes the timebase by querying Chaosnet hosts to find out the current dme. This is 
called automatically during system inidalizadon. You may want to call it yourself to 
correct the time if it appears to be inaccurate or downright wrong. See also time:set- 
local-time, page 777. 

time:daylight-savings-time-p hours date month year 

Returns t if daylight savings dme is in effect for the specified hour; otherwise, return nit. 
If year is less than 100, it is shifted by centuries undl it is within 50 years of the present 

t1me:day1ight-sav1ngs-p 

Returns t if daylight savings dme is currently in effect; otherwise, returns nil, 

tim 0 :month-length month year 

Returns the number of days in the specified month', you must supply a year in case the 
month is February (which has a different length during leap years). If year is less than 
100, it is shifted by centuries undl it is within 50 years of the present 
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timerleap-year-p year 

Returns t if year is a leap year; otherwise return nil. If jwr is less tlian 100, it is shifted 
by centuries until it is within 50 years of the present. 

time:verlfy-date date nioiiih year day-of-the-week 

If the day of the week of the date specified by dale, mouth, and year is the sttme as day- 
of-the-week, returns nil; otherwise, returns a string tJiat contains a suitable error message. 
If year is less Uian 100, it is shifted by centuries until it is within 50 years of tlie present. 

timerday-of-the-week-string day-of-the-week 8 lop{\owa\ long) 

Returns a string lepresenting the day of the week. As ustial, 0 means Monday, 1 means 
Tuesday, and so on. Possible values of wot/c are: 

:long Returns the full Hnglish name, such as "Monday", "Tuesday", etc. This 

is the default. 

:short Returns a tliree-letter abbreviation, such as "Mon", "Tue", etc. 

tmedium Returns a longer abbreviation, such as "Tues" and "Thurs". 

drench Returns the French name, such as "Lundi", "Mardi", etc. 

rgerman Returns the German name, such as "Montag", "Dienstag", etc. 
ritalian Returns the Italian name, such as "Lunedi", "Martedi", etc. 

t1me:month-stPlng month &optional imode:\oi\g) 

Returns a string representing the month of the year. As usual, 1 means January, 2 
means February, etc. Possible values of mode are: 

long Returns tlie full English name, such as "January", "February", etc. 

This is the default. 

:short Returns a three-letter abbreviation, such as "Jan", "Feb", etc. 

medium Returns a longer abbreviation, such as "Sept", "Novem", and "Decern". 

:roman Returns the Roman numeral for month (this convention is used in 

Europe). 

drench Returns the French name, such as "Janvier", "Fevrier", etc. 

igerman Returns the German name, such as "Januar", "Februar", etc. 

dtallan Returns the Italian name, such as "Gennaio", "Febbraio", etc. 

t1me:t1mezone-str1ng Aoptional (r/wezo«ctime:*timezone*) 

(daylight-savings-p (time:daylight-savings- p)) 

Return the three-letter abbreviation for this time zone. For example, if timezone is 5, 
then cither "EST" (Eastern Standard Time) or "CDT" (Central Daylight Time) is used, 
depending on daylight-savings-p. 


PS:<L.MAN>T1ME.TEXT.40 


8-JUN-84 



Miscclhincous Llscl'iil I 'unclions 784 l isp Miichinc Maniiiil 

35. Miscellaneous Useful Functions 

I’his chapter describes a number of functions tliat don’t logically fit in anywhere else. Most of 
these functions arc not normally used in programs, but arc “commands", i.c. tilings that you type 
directly at Lisp. 

35.1 Documentation 

documentation luime doc-iype 

Returns Uic documentation string of name in the role doc-lype. doc-type should be a 
symbol, but only its print-name matters, function as doc-type requests the documentation 
of name as a function, variable as doc-type requests tlic documentation of name as a 
variable, and so on. 

When doc-type is function, name can be any function spec, and the d(x:umcnUition string 
of its function definition is returned. Otherwise, name must be a symbol, and doc-type 
may be anything. However, only tliese values of doc-type are standardly used; 

Documentation of name as a special variable. Such dcKumentation is 
recorded automatically by defvar, defconst, defconstant, defparameter 
(page 33). 

Documentation of name as a type for typep. Recorded automatically 
when a documentation string is given in a deftype form (page 19), 

Documentation of name as a defstruct type. Recorded automatically by a 
defstruct for name (chapter 20, page 372). 

D(x:umentation on what it means to self a form tliat starts with name. 
Recorded when there is a documentation string in a defsetf of name (page 
345). 

Documentation of tlic flavor named name. Put on by the :documentation 
option in a defflavor for name (page 414). 

Documentation of the resource named name. Put on when there is a 
documentation string in a defresource of name (page 124). 

Documentation for name as a signal name. Put on when there is a 
documentation string in a defsignal or defsignal-explicit for name (page 
714). 

Documentation strings for any doc-type can be added to name by doing (sett 
(documentation name doc-type) string). 

The command Control-Shift-D in Zmacs and the rubout handler, used within a call to a 
ftinction, prints tlic dcKumcntation of that function. Control-Shift-V, within a symbol, prints the 
documentation of that symbol as a variable. 


variable 

type 

structure 

setf 

flavor 

resource 

signal 
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35.2 Hardcopy 

The hardcopy functions allow you to specify the printer to use on each call. 1 he default is 
set up by the site files for your site, but can be overridden for a particular machine in the 
LMLOCS file or by a user in his INl'f file. Any kind of printer can be used, no matter how it 
is actually driven, if it is hooked into tlie software properly as described below. 

A priiueviypc is a keyword tliat has appropriate properties; a primer is eiUier a printer-type or 
a list starting with one. The rest of the list can specify which printer of that type you want to 
use (perhaps with a host name i)r filename). 


The printer types defined by tlie system are: 

:dover Ihis printer type is used by itself as a printer, and refers to the Dover at Mil. 

;xgp ’Ihis printer type indicates a printer that is accessed by writing spool files in Mil 

XGP format. A printer would be specified as a list, (:xgp filename), specifying 
where to write the spool file. 

;press-file 'Ihis printer type is used in a list together with a file name, as in (:press-file 
"OZ:<RMS>FOO.PRESS"). Something is “printed” on such a printer by being 
converted to a press file and written under that name. 

hardcopy-fHe filename &rest options 

Print the file filename in hard copy on the specified printer or the default printer, options 

is a list of keyword argument names and values. There arc only two kcyw(nds that are 

always meaningful: :format and :printer. Everything else is up to the individual printer 

to interpret. The list here is only a paradigm or suggestion. 

:printer The value is the printer to use. The default is the value of si:*default- 

printer*. 

:format ITic value is a keyword that specifics the format of file to be parsed. 'The 

standard possibilities arc :text (an ordinary file of text), :xgp (a file of the 
sort once used by the XGP at MIF), ipress (a Xerox-style press file) and 
:suds-plot (a file produced by the Stanford drawing program). However, 
each kind of printer may define its own format keywords. 

:font 

:font"list The value of font is the name of a font to print the file in (a string). 

Alternatively, you can give dont-list and specify a list of such font names, 
for use if the file contains font-change commands. The intciprctation of a 
font name is dependent on the printer being used. I here is no necessary 
relation to IJsp machine display fonts. However, printers arc encouraged 
to use, by default, fonts that are similar in appearance to the Lisp 
machine fonts listed in the file’s attribute list, if it is a text file. 

:heading-font The value is the name of the font for use in page headers, if there are 
any. 

:vsp The value is the extra spacing to use between lines, in over and beyond 

the height of the fonts. 
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:page-headings 

If ihe value is non-nil, a heading is added to each page. 

:copies The value is the number of copies to print. 

:spool If the printer provides optional spooling, this argument says whether to 

spool (default is nil). Some printers may intrinsically always sp(H>l; others 
may have no way to spool. 

set-pr1nter-defauH-opt1on prhucr-iypc option value 

Sets a default for option for printers of type printer-type. Any use of die hardcopy 
functions with a printer of tliat type and no value specified for option will use the value 
value. 1-or example, 

(set-printer-default-option rdover ;spool t) 
causes output to Dover printers to be spooled unless the :spool option is explicitly 
specified with value nil. 

Currently dcfaultable options are :font, :font-list, :heading-font, :page-headings, :vsp, 
;copies, and :spool. 

hardcopy-stream stream &rcst options 

lake hardcopy-file but uses the text read from stream ratlicr than opening a file. 'Fhe 
dormat option is not allowed (since implementing it requires the ability to open the file 
with unusual open options). 

hardcopy-blt-array array left top right bottom &rcst options 

Print all or part of tlic bit-array array on the specified or default printer, options is a list 
of keyword argument names and values: the only standard option is printer, which 
specifics the printer to use. The default printer is si:*default-bit-array-printer*, or, if 
that is nil, si:‘default-printer. 

left, top, right and bottom specify tlie subrcctangle of the array to be printed. All four 
numbers measure from the top left corner (which is element 0, 0). 

hardcopy-status &optional printer (stream ‘standard-output*) 

Prints die status of printer, or the default printer, "fhis should include if possible such 
things as whether the printer has paper and what is in the queue. 

s1: *default-pr1nter* Variable 

This is tlic default printer. It is set from the :default-printer site option. 

si: *d 0 fault-bit-array-pr inter* Variable 

If non-nil, this is the default printer for printing bit arrays, overriding si:*default- 
printer‘. A separate default is provided for bit arrays since some printers that can print 
files cannot print bit arrays. 'Phis variable is set initially from the :default-bit-array- 
printer site option. 
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I )cfining a printer type: 

A printer type is any keyword that has suitable functions on the appropriate properties. 

'I'o be used with the function hardcopy-file, the printer type must have a si:print-file 
property. To be used with hardcopy-stream, tlie printer type must have a si:print-stream 
property, hardcopy-bit-array uses the si:print-bit-array property, hardcopy-status uses tlie 
si:print-status property. (The hardcopy functions' names arc not themselves used simply to avoid 
using a symbol in tlic global packtige as a property name of a symbol that might be in the global 
package as well). 

Hach property, to be used, should be a function whose first argument w'ill be the printer and 
whose remaining arguments will fit the same pattern as tliosc of the htirdcopy function the user 
called. (I'hcy will not ncccssiirily be the same arguments, as some additional keywords may be 
added to tlie list of keyword arguments; but they will fit tlie same description.) 

For example, 

(hardcopy-file "foo" :printer ’ ( :press-f i le "bar . press'*)) 
results in the execution of 

(funcall (get rpress-file 'si:print-file) 

’(:press-file "bar.press") 

"foo" :printer ’(:press-file "bar.press")) 

A printer type need not support operations that make no sense on it. For example, there is 
no si:print-status property on :press-file. 

35.3 Metering 

The metering system is a way of finding out what parts of your program use up the most 
time. When you run your program with metering, every function call and return is recorded, 
together with the time at which it took place. Page faults are also recorded. Afterward, the 
metering system analyzes tlie records and tells you how much time was spent executing withain 
each function. Because the records are stored in the disk partition called METR, there is room 
for a lot of data. 

Before you meter a program, you must enable metering in some or all stack groups. 
meter:enable is used for this. Then you evaluate one or more forms with metering, perhaps by 
using meter:test or meter:run. Finally, you use meter:analyze to summarize and print the 
metering data. 

There arc two parameters that control whether metering data arc recorded. First of all, the 
variable sys:%meter-microcode-enables contains bits that enable recording of various kinds of 
events. Secondly, each stack group has a flag that controls whether events arc recorded while 
running in that stack group. 
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sys:%met 0 r microcode-enables I’tniMe 

H.nablos recording ol' mcicring daia. l-lacli bit controls recording of one kind of event. 

1 This bit enables recording of page faults. 

2 This bit enables recording of consing. 

4 This bit enables recording of function entry and exit. 

8 niis bit enables recording of slack group switching. 

I'hc value is nomiiilly zero, which turns off all recording. 

These arc the functions used to control which stack groups do metering: 

meter:enable &rcst ihings 

luiablcs metering in the stack groups specified by things, luich thing in things may be a 
stack group, a process (which specifics the process’s stack group), or a window (which 
specifics the window’s puKCSs’s stack group), t is also allowed. It enables mcicring in all 
stack groups. 

meter:disable &rcst things 

Disables metering in the stack groups specified by things. The arguments allowed arc the 
same as for meter:enable. (meter:disable t) turns off (meter:enable t), but docs not 
disable slack groups enabled individually.. (meter:disable) disables all suick groups no 
matter how you specified to enable them. 

meter rmetered-objects Variable 

I'his is a list of all tlie things you have enabled with meter:enable and not disabled. 

These arc the fimciions to evaluate forms with metering: 

meter:run fonm 

Clears out the metering data and evaluates the fomis with sys:%meter-microcode- 
enables bound to 14 octal (record function entry and exit, and sUick group switching). 
Any of the evaluation that takes place in enabled stack groups will record metering data. 

meter:test form (enables #o^4) 

Clears out tlie metering data, enables metering for the current stack group only, and 
evaluates form with sys:%meter-microcode-enables bound to enables. 

This is how you print the results: 

meter: analyze &kcy analyzer stream file buffer return info &allow-othcr-kcys 

Analyzes tlic data recorded by metering, analyzer is a keyword specifics a kind of 
analysis. :tree is the default. Another useful alternative is ;list-events. Particular 
analyzers handle other keyword arguments in addition to those listed above. 

I hc output is printed on stream, written to a file named file, or put in an editor buffer 
named buffer (at most one of these three arguments should be specified). The default is 
to print on ‘standard-output*. 
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Analyzing the mclcring data involves creating a large intermediate data base. Normally 
this is created afresh each time meter:analyze is called. If you specify a non-nil value for 
return, die intcmicdiatc data structure is returned by meter:analyze, and can be passed 
in on another call as the info argument. This can save time. But you can only do tliis if 
you use tlte same analyzer each time, as diilerent analyzers use dilferent terinporary data 
structures. 

The default analyzer dree prints out tlie amount of run time and real time spent executing 
each function that was called. The real lime includes time spend wailing and time spent writing 
metering data to disk; for compuunional tasks, the latter makes the real time less useful Uian the 
run lime, dree handles these additional keyword arguments to meter:anaiyze: 

:find-callers ITie argument for Utis keyword is a function spec or a list of function specs. A 

list of who called the specified functions, and how often, is printed instead of the 

usual output. 

:stack-group The argument is a stack group or a list of them; only the activities in those stack 
groups are printed. 

;sort-function The argument is the name of a suitable sorting function that is used to sort the 

items for the various functions that were called. Sorting hinctions provided 

include meter:max-page-faults, meterimax-calls, meter:max-run-time (die 
default), metenmax-real-time, and meter:max-run-time-per-call. 

:summarize The argument is a function spec or a list of function specs; only those functions 
statistics are printed. 

tinclusive If this is non-nil, the times for each function include the time spent in executing 
subroutines called from the function. 

Note: if a function is called recursively, the time spent in the inner call(s) is 
counted twice (or more). 

The analyzer dist-events prints out one line about each event recorded. The line contains 
the nm time and real time (in microseconds), the running count of page faults, the stack group 
name, the function that was running, the stack depth, the type of event, and a piece of data. 
For example; 

000 ZMACS-WINDOWS METER;TEST 202 CALL SI:EVAL 
115 43 0 ZMACS-WINDOWS METER:TEST 202 RET SItEVAL 

180 87 0 ZMACS-WINDOWS METERiTEST 202 RET CATCH 

real run pf stack-group function stack event data 

time time level type 

dist-events is often useful with recording of page faults (sys:%meter-microcode-enables set 
to 1). 
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meter:reset 

Clears out all metering data. 

Because metering records pointers to Lisp objects in a disk partition which is not part of Uic 
Lisp address space, garbage collection is inhibited (by arresting tlic gc process) when you turn on 
metering. 

meter: resume-gc'^process 

Allows garbage collection to continue (if it is already turned on) by unarresting it. 

35.4 Poking Around in the Lisp World 

who- calls X &optional package (iuheritorsi) {iiiheriledX) 

X must be a symbol or a list of symbols, who-calls tries to find all of tlic functions in 
tlic Lisp world tliat call jr as a function, use x as a variable, or use jr as a constant. 
(Constants which arc lists containing x arc not found.) It tries to find all of the functions 
by searching all of tlic function cells of all of the symbols in package and packages that 
inherit from package (unless inheritors is nil) and packages package inherits from (unless 
inherited is nil), package defaults to the global package, which means that all normal 
packages are checked. 

If who-calls encounters an interpreted function definition, it simply tells you if x appears 
anywhere in the interpreted code, who-calls is smarter about compiled code, since it has 
been nicely predigested by tlic compiler. Macros expanded in the compilation of the code 
can be found because they arc recorded in the caller’s debugging info alist, even though 
tlicy are not actually referred to by the compiled code. 

If X is a list of symbols, who-calls does them all simultaneously, which is faster than 
doing them one at a time. 

who-uses is an obsolete name for who-calls. 

The editor has a command, Meta-X List Callers, which is similar to who-calls. 

The symbol :unbound-function is treated specially by who-calls. (who-calls 
:unbound-function) searches all the compiled code for any calls through a symbol that is 
not currently defined as a function. ITiis is useful for finding errors such as functions you 
misspelled the names of or forgot to write. 

who-calls prints one line of information for each caller it finds. It also returns a list of 
the names of all die callers. 

what-f1l0S-call x &optional package (inheritorsX) {inheritedX) 

Similar to who-calls but returns a list of the pathnames of all the files tliat contain 
functions that who-calls would have printed out. 'ITiis is useful if you need to recompile 
and/or edit all of those files. 
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apropos substring &optional package &kcy (mheritorsi) inherited dont-print predicate boundp 
Jboundp 

(apropos substring) tries to find all symbols whose print-names contain substring as a 
substring. Whenever it finds a symbol, it prints out the symbol’s name; if the symbol is 
defined as a function and/or bound to a value, it tells you so and prints the names of the 
arguments (if any) to the function. 

If predicate is non-nil, it should be a function; only symbols on which the function 
returns non-nil are counted. In addition, Jboundp non-nil means only symbols with 
function definitions arc considered, and boundp non-nil means that only symbols with 
values arc considered. 

apropos looks for symbols on package, and all packages tliat use package (unless 
inheritors is nil). If inherited is non-nil, all packages used by package arc searched as 
well, package can be a package or a symbol or string naming a package. It can also be a 
list of packages, symbols and strings: all of tlic packages tliiis specified arc searched. 
package defaults to a list of all packages except invisible ones. 

apropos returns a list of all the symbols it finds. If dont-print is non-nil, that is all it 
docs. 

sub-apropos substring starting-list &key predicate dont-print 

Finds all symbols in starting-list whose names contain substring, and tliat satisfy predicate. 
If predicate is nil, the substring is the only condition. Tlie symbols arc printed if dont- 
print is nil. A list of the symbols found is returned, in any case. 

This function is most useful when applied to the value of *, after apropos has returned 
a long list. 

where-Is pname &optional package 

Prints the names of all packages that contain a symbol with the print-name pname. If 
pname is a string it gets upper-cased. The package package and all packages that inherit 
from it are searched, package can be a package or tlic name of a package, or a list of 
packages and names. It defaults to a list of all packages except invisible ones, where-is 
returns a list of all the symbols it finds. 

describe x 

describe tries to tell you all of the interesting information about any object x (except for 
array contents), describe knows about arrays, symbols, floats, packages, stack groups, 
closures, and FEFs, and prints out the attributes of each in human-readable form. 
Sometimes objects found inside x arc described also; such recursive descriptions are 
indented appropriately. For instance, describe of a symbol also describes the symbol’s 
value, its definition, and each of its properties, describe of a float (full-size or short) 
shows you its internal representation in a way that is useful for tracking down roundoff 
errors and the like. 

If X is a named-structure, describe invokes the :describe operation to print the 
description, if that is supported. I’o understand this, you should read the section on 
named structures (see page 390). If the :describe operation is not supported, describe 
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looks on ihc namcd-structurc symbol for information that might have been left by 
defstruct: this information would tell it what tlie symbolic names for die entries in the 
structure arc, and describe knows how to use the names to print out what each field's 
name and contents is. 

describe of an instance always invokes the :describe operation. All flavors support it. 
since si:vanilla-flavor defines a mctliod for it. 

describe always returns its argument, in ease you want to do something else to it. 

Inspect X 

A window-oriented vci^sion of describe. See the window system d(x:umcntation for 
details, or try it and type Help. 

disassemble function 

Prints out a human-readable version of the macro-instructions in function, function should 
be a FKF, or a function spec whose definition is a FEF. The macro-code instruction set 
is explained in chapter 31, page 752. 

The grindef flinction (see page 528) may be used to display the definition of a non-compiled 
function. 

room &rcst areas 

Prints a summary of memory usage. 

llic first line of output tells you tlic amount of physical memory on the machine, the 
amount of available virtual memory not yet filled with data (that is, the portion of the 
available virtual memory that has not yet been allocated to any region of any area), and 
tlic amount of wired physical memory (i.c. memory not available for paging). 

Following lines tell you how much room is left in some areas. For each area it tells you 
about, it prints out the name of the area, the number of regions tliat currently make up 
the area, the current size of the area in kilowords, and the amount of the area that has 
been allocated, also in kilowords. If the area cannot grow, the percentage that is free is 
displayed. 

(room) tells you about those areas that arc in the list that is the value of tlic variable 
room. These are the most interesting ones. 

(room areal areal...) tells you about those areas, which can be cither the names or the 
numbers. 

(room t) tells you about all the areas. 

(room nil) docs not tell you about any areas; it only prints the first line of output. 
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room 


Variable 


IIk value of room is a list of area names and/or area numbers, denoting the areas that 
the function room should describe if given no arguments. Its initial value is: 
(working-storage-area macro-compi1ed-program) 

35.5 UUlily Programs 

ed &optional x 

ed is the main function for getting into tlic editor, /macs. The commands of /macs arc 
very similar to those of Hmacs. 

(ed) or (ed nil) simply enters tlic editor, leaving you in the same buffer as the last time 
you were in the editor. It has the same effect as typing System E. 

(ed t) puts you in a fresh buffer with a generated name (like nUFKKR-4). 

(ed pathname) edits that file, pathname may be an actual patlmame or a string. 

(ed ’foo) tries hard to edit tlie definition of Uic foo function. It can find a buffer or file 
containing the source code for foo and position tlic cursor at the beginning of the code. 
In general, foo can be any function-spec (sec section 11.2, page 223). 

(ed ’zwei:reload) reinitializes the editor. H forgets about all existing buffers, so use this 
only as a last resort. 

zwe1 :sav8-an-f fles 

'fliis function is useful in emergencies in which you have modified material in Zmacs 
buffers that needs to be saved, but the editor is partially broken. 'ITiis function docs what 
the editor’s Save Alt Files command does, but it stays away from redisplay and other 
advanced facilities so tliat it might work if other things arc broken. 

direct &optional pathname 

Puts up a window and edits the directory named by pathname, which defaults to the last 
file opened. While editing a directory you may view, edit, compare, hardcopy, and 
delete the files and subdirectories it contains. While in the directory editor type the Help 
key for further information. 

mall &optional user text call-editoi^anyway 

Sends the string text as mail to user, user should also be a string, of the form 
"usernameQhostname". Multiple recipients separated by commas are also allowed. 

If you do not provide two arguments, mail puts up an editor window in which you may 
compose the mail. Type the End key to send the mail and return from the mail function. 

The window is also used if call-editor-anyway is non-nil. 
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bug &optional topic text call-eJitor-auyway 

Reports a bug. topic is tlic name of the faulty program (a symbol or a string). It defaults 
to lispm (the l.isp Machine system itsclO- text is a string which contains die information 
to report. If you do not provide two arguments, or if call-editor-cmyway is non-nil, a 
window is put up for you to compose the mail. 

bug is like mail but includes information about tlie system version and what machine you 
are on in tlic text of tlic message. Phis infomiation is important to the maintainers of the 
faulty program; it aids them in reproducing the bug and in determining whether it is one 
that is already being worked on or has already been fixed. 

print-notifications Aoptional (fnmtO) to 

Reprints any notifications diat have been received, from and to arc used to restrict which 
notifications arc printed; both count from the most recent notification as number 0. 'ITius, 
(print-notifications 2 8) prints six notifications after skipping the two most recent. 

The difFcrcncc between notifications and sends is that sends come from other users, while 
notifications arc usually asynchronous messages from the Lisp Machine system itself. 
However, the default way for the system to inform you about a send is to make a 
notification! So print-notifications normally includes all sends as well. 

Typing Terminal 1 N pops up a window and calls print-notifications to print on it 

si:pr1nt-d1sk-epror-log 

Prints information about tlie half dozen most recent disk errors (since the last cold boot), 
peek &optional character 

Selects the PEEK utility, which displays various information about the system, periodically 
updating it. PEEK has several modes, which arc entered by typing a single key which is 
the name of the mode or by clicking on the menu at the top. The initial mode is 
selected by the argument, character. If no argument is given, PEEK starts out by 
explaining what its modes are. 

time form 

Evaluates form and prints the length of time that the evaluation took. The values of form 
are returned. 

Note that time with no argument is a function to return a time value counting in 60ths of 
a second; see page 777. "I’his unfortunate collision is a consequence of Common Lisp. 
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35.6 f’hc Lisp Listen Loop 

I'hcsc funciions constitute Uic 1.isp top level rcad-cval-print loop or lisicn loop and its 
ass(x:iatcd functions. 

s1: Usp-top-level 

I'his is die first function called in the initial l.isp environment. It calls lisp-reinitialize, 
clears tlic screen, and calls si:lisp-top-level1. 

1isp-relnitlalIze 

This function docs a wide variety of things, such as resetting the values of various global 
constants and initializing the error system. 

s1: l1sp-top-level 1 *lenninaI-io* 

This is the actual listen loop. Within it, ‘terminal-io* is bound to die argument 
supplied. This is die stream used for reading and printing if ‘standard-input* and 

‘standard-output* are synonyms for ‘terminal-io‘, as dicy normally are. 

0 

The listen loop reads a form from ‘standard-input*, evaluates it, prints the result (with 
escaping) to ‘standard-output*, and repeats indefinitely. If several values are returned 
by the form all of them are printed. Also the values of *, +, -, //, + + , + + + , 

•“ and ‘values* are maintained (see below). 

break fomial-string &rest foimat-args 

Enters a breakpoint loop, which is similar to a Lisp top level loop, format-string and the 
formai-args are passed to format to print a message. 

;Breakpoint message; Resume to continue, Abort to quit, 
and then enters a loop reading, evaluating, and prindng forms. A difference between a 
break loop and the top level loop is that when reading a fonn, break checks for the 
following special eases: If the Abort key is typed, control is returned to the previous 
break or error-handler, or to top-level if there is none. If the Resume key is typed, 
break returns nil. If the list (return form) is typed, break evaluates fonn and returns the 
result, without ever calling the function return. 

Inside the break loop, the streams ‘standard-output*, ‘standard-input*, and query-io 
are bound to be synonymous to ‘terminal-io‘: ‘terminal-io* itself is not rebound. 
Several other internal system variables are bound, and you can add your own symbols to 
be bound by pushing elements onto tlie value of the variable sys;‘break-bindings‘ (see 
page 797). 

break used to be a special form whose first argument was a string or symbol which was 
simply printed without evaluating it. In order to facilitate conversion, break really still is 
a special form. If the call appears to use the old conventions, it behaves in the old way, 
but the compiler issues a warning if it secs such code. 
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pr1nl Variable 

The value of this variable is normally nil. If it is non-nil, Uicn the rcad-cval-print loop 
uses its value instead of the definition of prin1 to print tltc values returned by functions. 
This hook lets you control how things arc printed by all read-eval-print loops—tltc Lisp 
top level, the break function, and any utility programs that include a read-eval-print loop. 
It docs not affect output from programs tliat call the prin1 function or any of its relatives 
such as print and format; if you want to do iliat, read about customizing die printer, on 
section 23.1, page 513. If you set print to a new function, remember that die read-eval- 
print loop expects die function to print the value but not to output a return character or 
any other delimiters. 

Variable 

While a form is being evaluated by a read-eval-print loop, - is bound to the form itself. 

+ Variable 

While a form is being evaluated by a read-eval-print loop, + is bound to the previous 
fonn that was read by the loop. 

Variable 
Variable 

While a form is being evaluated by a read-eval-print loop, * is set to the result printed 
the last time through the loop. If there were several values printed (because of a 
multiple-value return), * is bound to the first value, //is bound to a list of all the 
values of die previous form. 

If evaluation of a form is aborted, * and // remain set to the results of the last 
successfully completed form. If evaluation is successful but printing is aborted, * and // 
arc already set for the following form. 

Note that when using Common Lisp syntax you would type just /. 

++ Variable 

+ + holds die previous value of +, that is, the form evaluated two interactions ago. 

+++ Variable 

+ + + holds the previous value of + +. 

• • Variable 

III! Variable 

Hold the previous values of * and //, that is, the results of the form evaluated two 
interactions ago. Only forms whose evaluation is successful cause the values of * and // 
to move into ** and ////. 

Note that when using Common Lisp syntax you would type just //, 


« 

// 
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«•* Variable 

/Hm Variable 

Mold the previous values of ** and ////, tliat is. the results of the form evaluated three 
interactions ago. Note Uiat when using Common Lisp syntax you would type just ///. 

•values* Variable 

‘values* holds a list of all lists of values produced by evaluation in this l.isp listener, 
(car ’values*) is nearly equivalent to //. (cadr ’values*) to ////. and so on. The 
difference is iliat an element is pushed on ’values* for each form whose evaluation is 
started. If evaluation is aborted, the element of ’values* is nil, 

sys:*break-b1nd1ngs* Variable 

When break is called, it binds some special variables under control of die list which is 
die value of sys:’break-bindings*, liach element of die list is a list of two elements: a 
variable and a form diat is evaluated to produce the value to bind it to. The bindings 
happen sequentially. Users may push things on this list (adding to die front of it), but 
should not replace the list wholesale since several of the variable bindings on diis list are 
essential to die operation of break. 

I1sp-crash-11st Variable 

'Phe value of lisp-crash-list is a list of forms, lisp-reinitialize sequentially evaluates 
dicse forms, and dien sets lisp-crash-list to nil. 

In most cases, the iniiializaiiou facility should be used rather than lisp-crash-list. Refer 
to chapter 33, page 111. 


35.7 The Garbage Collector 


gc-on 

Turns automatic garbage collection on. Garbage collection will happen when and as 
needed. Automatic garbage collection is off by default. 

Since garbage collection works by copying, you are asked for confimiation if there may 
not be enough space to complete a garbage collection even if it is started immediately. 


gc-off 

Turns automatic garbage collection off. 


gc-on 


Variable 

t when garbage collection is on. nil when it is not. You cannot control garbage collection 
by setting this variable; it exists so you can examine it. In particular, you can tell if the 
system found it necessary to turn off garbage collection because it was close to running 
out of virtual memory. 


Normally, automatic garbage collection happens in incremental mode; that is, scavenging 
happens in parallel with computation. b:ach consing operation scavenges or copies four words per 
word consed. In addition, scavenging goes on whenever the machine appears idle. 
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si: Inhibit-ldle-scavenging-f lag Variable 

If this is non-nil, scavenging is not done during idle time. 

If you are running a noninteractive crunching program, the incremental nature of garbage 
collection may not be helpful. Then you can make garbage collection more efficient by making it 
a batch process. 

si: gc-reclalm-lmmedlately Variable 

If this variable is non-nil. automatic garbage collection is done as a batch operation: 
when the garbage collection priKCSS decides that the time has come, it copies all the 
useful dau» and discards tlic old address space, running full blast. (It is still pos.siblc to 
use the machine while tltis is going on, but it is slow.) More specifically, the garbage 
collection process scavenges and reclaims oldspacc immediately right after a flip happens, 
using all of the machine's physical memory. 'Hiis variable is only relevant if you have 
turned on automatic garbage collection with (gc-on). 

A batch garbage collection requires less free space than an incremental one. If there is 
not enough space to complete an incremental garbage collection, you may be able to win 
by selecting batch garbage collection instead, 

si: gc-recla1m-1mraed1ately-1f-necessary Variable 

If this variable is non-nil, then automatic garbage collection is done in batch mode if, 
when the flip is done, tlicrc docs not seem to be enough space left to do it incrementally. 
This variable’s value is relevant only if si:gc-reclaim-immediately is nil. 

si :gc-f lip-ratio Variable 

This variable tells the garbage collector what fraction of the data it should expect to have 
to copy, after each flip. It should be a positive number no larger than one. By default, 
it is one. But if your program is consing considerable amounts of garbage, a value less 
than one may be safe. The garbage collector uses this variable to figure how much space 
it will need to copy all the living data, and therefore indirectly how often garbage 
collection must be done. 

si; gc-f 11p-m1n1inum-rat1o Variable 

This value is used, when non-nil, to control warnings about having too little space to 
garbage collect. Its value is a positive number no greater than one, just like that of 
si:gc-flip-ratio. ITie difference between the two is that si:gc-flip-ratio controls when 
garbiigc collection is recommended, whereas si:gc-flip-minimum-ratio controls when the 
system considers the last possible time to do so. If si:gc-flip-minimum-ratio is nil, 
si:gc-flip-ratio serves both purposes. 

Garbage collection is turned off if it appears to be about to run out of memory. You get a 
notification if this happens. You also get a notification when you are nearly at the point of not 
having enough space to guarantee garbage collecting successfully. 

In addition to turning on automatic garbage collection, you can also manually request one 
immediate complete collection with the function si:full-gc. The usual reason for doing this is to 
make a band smaller before saving it. si:full-gc also resets all temporary' areas (sec shreset- 
temporary-area, page 299). 
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s1:fun-gc 

I’erforms a complete garbage collection immediately. This docs not turn automatic garbage 
collection on or off; it performs tlic garbage collection in tlic prtK'css you call it in. A 
full gc of the standard system takes about 7 minutes, currently. 

si rclean-up-static-area area-number 

This is a more selective way of causing static areas to be garbage collected once. ITic 
argument is the area number of a static area: that particular area will be garbage collected 
the next time a garbage collection is done (more precisely, it will be copied and discarded 
after tbc next flip). If you tlicn call si:full-gc. it will happen then. 


gc-status 

The function gc-status prints information related to garbage collection. When scavenging 
is in progress, it tells you how the task is progressing. While scavenging is not in 
progress and oldspacc docs not exist, it prints information about how soon a new flip will 
be required. 

While a garbage collection is not in progress, the output from gc-status looks like tliis: 
Dynamic (new+copy) space 557,417, Old space 0, Static 3,707,242, 

Free space 10,453,032, with 10,055,355 needed for garbage collection 
assuming 100% live data (SI:GC-FLIP-RATI0 = 1). 

If GC is turned on, a flip will happen in 397,677 words. 

Scavenging during cons Off, Idle scavenging On, 

Automatic garbage collection Off. 

GC Flip Ratio 1, GC Reclaim Immediately Off 
or 

Dynamic (new+copy) space 561,395, Old space 0, Static 3,707,242, 

Free space 10,453,032, with 10,058,670 needed for garbage collection 
assuming 100% live data (SI:GC-FLIP-RATIO = 1). 

A flip will happen in 394,362 words. 

Scavenging during cons On, Idle scavenging On, 

Automatic garbage collection On. 

GC Flip Ratio 1, GC Reclaim Immediately Off 

The “dynamic space” figure is the amount of garbage collectable space and the “static” figure 
is the amount of static space used. ITiere is no old space since an old space only exists during 
garbage collection. 


The amount of space needed for garbage collection represents an estimate of how much space 
user programs will use up while scavenging is in progress. It includes a certain amount of 
padding. The difference between the free space and tliat amount is how much consing you can 
do before a garbage collection will begin (if automatic garbage collection is on). 

'fhe amount needed for a garbage collection depends on the value of si :*gc-reclaim- 
immediately*; more if it is nil. 

While a garbage collection is in progress, the output looks like this: 
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Incremental garbage collection now in progress. 

Dynamic (new+copy) space 45,137, Old space 972,514, Static 3,707,498, 
Between 3,701,440 and 4,629,998 words of scavenging left to do. 

Free space 9,289,795 (of which 928,558 might be needed for copying). 
Ratio scavenging work/free space = 0,55. 

Scavenging during cons On, Idle scavenging On, 

Automatic garbage collection On. 

GC Flip Ratio 1, GC Reclaim Immediately Off 


Notice tliat most of the dynamic space has become old space and new space is small. Not 
much has been copied since tlie flip Umk place. Ihe maximum and minimum estimates for the 
ainount of scavenging arc based on different limits for how much of old space may need to be 
copied; as scavenging progresses, the maximum decreases steadily, but tlic minimum may 
increase. I'hc free space is smaller now, but it will get larger when scavenging is finished and old 
space is freed up. (The total amounts arc not the same now because unused parts of regions may 
not be included in any of die figures.) 


si: set-scavenger-ws mmber^of-pages 

Incremental scavenging is restricted to a fixed amount of physical memory to reduce its 
interference with your other activities. 

'fhis flinction specifics the number of pages of memory that incremental garbage collection 
can use. 256 is a good value for a 256k machine. If the garbage collector gets very poor 
paging performance, use of this function may fix it. 


35.8 Logging In 

Logging in tells the Usp Machine who you arc, so tliat other users can see who is logged in, 
you can receive messages, and your INIT file can be run. An INIT file is a Lisp program which 
gets loaded when you log in; it can be used to set up a personalized environment. 

When you log out, it should be possible to undo any personalizations you have made so that 
they do not affect the next user of the machine. I’hcrcfore, anything done by an INIT file 
should be undoable. In order to do this, for every form in the INIT file, a Lisp form to undo 
its effects should be added to the list that is the value of logout-list. ITie login-forms construct 
helps make this easy; see below. 

user-Id Variable 

ITie value of user-id is citlier the name of the logged in user, as a string, or else an 
empty string if there is no user logged in. It appears in the who-line. 

logout-11st Variable 

The value of logout-list is a list of forms to be evaluated when the user logs out. 
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login name &oi)tional host inliibihinH-file 

Sets your name (the variable user-id) to name and logs in a file scrv'cr <»n host, host also 
becomes your default file host. Tbe default value of host depends on which l .isp Machine 
you use using; it is called die assttcialcd machine (see page 815). login also runs the 
login initializatit)!! list (see page 773). 

If host requires passwords for logging in you arc asked for a password. Adding an 

asterisk at tlic front of your password enables tiny special capabilities you may be 

authorized to use, by calling fs:enable-capabilities (page 609). 

Unless inhibil-inil-file is specified as non-nil, login loads your init file if it exists. On I'I'S, 
your init file is name LISPM on your home directory. On TOI*S-20 your init file is 
LISPM.INIT on your directory. On VMS, it is LISPM.INI. On Unix, it is lispm.init. 

If anyone is logged into the machine already, login logs him out before logging in name. 
(See logout.) Init files should be written using the login-forms construct so that logout 
can undo them. Usually, however, you cold-boot the machine before logging in, to 
remove any traces of die previous user, login returns t. 

logl &rest options 

Like login but the arguments arc specified differently, options is a list of keywords and 
values; the keywords :host and :init specify the host to log in on and whether to load the 

init file if any. Any other keywords are also allowed, logl itself ignores them, but the 

init file can act on them. Ihc purpose of logl, as opposed to login, is to enable you to 
specify other keywords for your init file’s sake. 

si :us0r-in1t-opt1ons Variable 

During the execution of the user’s init file, inside logl, this variable contains the 
arguments given to log1. Options not meaningful to log1 itself can be specified, so that 
the init file can find them here and act on them. 

logout 

First, logout evaluates the forms on logout-list. Then it sets user-id to an empty string 
and logout-list to nil. 'Fhen it runs the :logout initialization list (see page 773), and 
returns t. 

login-forms undoable-forms... Macro 

The body of a login-forms is composed of forms to be evaluated, whose effects are to be 
undone if you log out. For example, 

(login-forms 

(setq fs:*defaults-are-per-host* t)) 
would set the variable immediately but arrange for its previous value to be restored if you 
log out. 

login-forms is not an AI program; it must be told how to undo each ftmetion that will 
be used immediately inside it. ITiis is done by giving the function name (such as setq) a 
:undo-function property which is a function that takes a form as an argument and 
returns a form to undo the original form. For setq, this is done as follows: 
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(defun (setq :undo-function) (form &aux results) 

(do ((1 (edr form) (eddr 1))) 

((null 1)) 

(cond ((boundp (car 1)) 

(push '(setq ,(car 1) ’.(symeval (car 1))) results)) 
(t (push '(makunbound (car 1)) results)))) 

•(progn , .results)) 

Undo functions arc standardly provided for die functions setq. pkg-goto-globally, setq- 
globally, add-initialization, deff, defun, defsubst macro, advise and zweirset- 
comtab. Constmets which niacrocxpand into uses of those functions arc also supported. 

Note dial setting *read-base* and *print-base* should be done with setq-globally 
radicr dian setq, since those variables arc likely to be bound by the load function while 
the in it file is executed. 

logln-setq {variable value)... Macro 

login-setq is like setq except that it puts a setq form on logout-list to set the variables 
to dicir previous values, login-setq is obsolete; use login-forms around a setq instead. 

login-eval x 

login-eval is used for functions that arc “meant to be called” from INIT files, such as 
zwei:set-comtab-return-undo, which conveniently return a form to undo what they did. 
login-eval pushes the result of the foim x onto logout-list. It Is obsolete now because 
login-forms is a cleaner interface. 

si :undoable-forras-l undo-list-name forms Aoptional complaint-string 

This is what login-forms uses. Jbnns is a list of forms; they are evaluated and forms for 
undoing dicir effects arc pushed onto the value of the symbol undo-list-name. If an 
element of forms has no known way to be undone, a message is printed using the string 
complaint-string. For login-forms, die string supplied is "at logout". 


35.9 Dribble Files 

dribble &optional filename 

With an argument, dribble opens filename as a ‘dribble file’ (also known as a ‘wallpaper 
file’) and then enters a Lisp listen loop in which ‘standard-input* and ‘standard- 
output* arc rebound to direct all the output and echoing they do to the file as well as to 
the terminal. 

Dribble output can be sent to an editor buffer by using a suitable padinamc; see section 
24.7.6, page 575. 

Calling dribble with no arguments terminates dribbling: it throws to the original call to 
dribble, which closes the file and returns. 
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dplbble-all &opiional filename 

Like dribble except lliat all input and output goes to the dribble file, including break 
loops, queries, warnings and sessions in the debugger. I his works by binding *terminal- 
io* instead of ‘standard-output* and ‘standard-input*. 

35.10 Version Information 

Common Lisp defines several standard ways of inquiring about the identity and capabilities of 
the Lisp system you arc using. 

•features* Variable 

A list of atoms which describe die software and hardware features of the Lisp 
implementation. By default, this is 

(:1oop :defstruct :lispm :cadr :mit ;chaos :sort :fasload rstring 
:newio :roman :trace :grindef :grind ;common) 

Most important is the symbol :lispm; diis indicates diat the program is executing on the 
Lisp Machine. :cadr indicates the type of hardware, :mit which version of the Lisp 
Machine operating system, and :chaos diat the Chaosnet protocol is available. :common 
indicates that Common Lisp is supported. 

Most of the other elements are for Maclisp compatibility. Common Lisp defines the 
variable ‘features* but docs not define what should appear in the list. 'ITie order of 
elements in the list has no significance. Membership checks should use string-equal so 
that packages are not significant 

The #+ and #- read constructs (page 525) check for the presence of an element in this 
list. Thus, #+lispm when read by a Lisp Machine causes the following expression to be 
significant, because :lispm is present in the features list 

llie remaining standard means of inquiry are specified by Common Lisp to be functions 
rather than variables, for reasons that seem poorly thought out. 

I 1 sp- 1 mplem 0 ntat 1 on-typ 0 

Returns a string saying what kind of Lisp implementation you are using. On the Lisp 
Machine it is always "Zetalisp". 

I 1 sp- 1 rapl 0 m 0 ntat 1 on-v 0 ps 1 on 

Returns a string saying the version numbers of the Lisp implementation. On the Lisp 
Machine itjooks something like 

"System 98.3, CADR 3.0, ZMAIL 52.2". 

machine-type 

Returns a string describing the kind of hardware in use. It is "CADR" or "LAMBDA". 


PS;<L.MAN>FD-HAC.TEXT.47 


8-JUN-84 



MiKHing and Disk Partilions 804 l isp Machine Manual 


machine-version 

Returns a string describing the kind of hardware and mierwode version. It sUirts with tlic 
value of machine-type. It might be "CADR Microcode 309". 

machine-instance 

Returns a string giving tlic name of this machine. Do not be confused; the value is a 
string, not an inshmee. Hxample: "CADR-18". 

software-type 

Returns a string describing tlie type of operating system software tliat Lisp is working 
with. On the Lisp Machine, it is always "Zetalisp", since the Lisp Machine Lisp 
software is the operating system. 

software-version 

Returns a string describing the version numbers of tlic operating system software in use. 
This is the same as lisp-implementation-version on tlie Lisp Machine since the same 
software is being described. 

short-sito-name 

Returns a siring giving briefly the name of the site you are at. A site is an institution 
which has a group of Lisp Machines. 4'he string you get is tlie value of the :short-site- 
name site option as given in SYS: SITE; SITE LISP. See section 35.12, page 810 for 
more information. Example: "MIT Al Lab". 

long-s1te-namo 

Returns a string giving a verbose name for the site you are at Tliis string is specified by 
the site option :long-site-name. Example: "Massachusetts Institute of Technology, 
Artificial Intelligence Laboratory". 

35.11 Booting and Disk Partitions 

A Lisp Machine disk is divided into several named partitions (also called bands sometimes). 
Partitions can be used for many things. Every disk has a partition named PAGE, which is used 
to implement tlie virtual memory of tlie Lisp Machine. When you run Lisp, this is where the 
Lisp world actually resides. There are also partitions that hold saved images of the Lisp Machine 
microcode, conventionally named MCRn (where n is a digit), and partitions that hold saved 
images of Lisp worlds, conventionally named LOD/i. A saved image of a l.isp world is also 
called a virtual memory load or system load. The microcode and system load arc stored separately 
so that the microcode can be changed without going through the time-consuming process of 
generating a new system load. 

Tbe directory of partitions is in a special block on the disk called the label. The label names 
one of the partitions as the current microcode and one as the current system load. When you 
cold-boot, the contents of the current microcode band are loaded into the micrtxrodc memory, 
and then the contents of the current saved image of the Lisp world is copied into the PAGE 
partition. Then Lisp starts running. When you warm-boot, the contents of the current microcode 
band arc loaded, but Lisp starts running using the data already in tlie PAGE partition. 
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l-'ur each partition, the directory of partitions contains a brief textual description of the 
contents of the partition. For microcode partitions, a typical dc.scription might be "UCADR 310"; 
this means that \crsion 310 of the microcode is in tlic partition. For saved Lisp images, it is a 
little more complicated. Ideally, die description would say which versions of which systems are 
loaded into the band. Unfortunately, there isn’t enough room for diat in most eases. A typical 
description is "99.4 Daed 5.1", meaning that this band contains version 99.4 of System and 
version 5.1 of Daedalus. The description is created when a l.isp world is saved away by disk- 
save (see below). 

35.11.1 Manipulalin}'the Label 

pr1nt-d1sk-1abel &optional {uniiO) (.v/mw; ’standard-output*) 

Prints a description of the label of die disk specified by unit onto stream. The description 
sUirts with the name of die disk pack, various infonuation about the disk diat is generally 
uninteresting, and the names of the two current load partitions (microcode and saved Lisp 
image). This is followed by one line of description for each partition. F,ach one has a 
name, disk address, size, and textual comment, d'he current miertKode partition and the 
current system load partition are marked with asterisks, each at the beginning of the line. 

unit may be the unit number of the disk (most Lisp machines just have one unit, number 
0), or the host name of another Lisp Machine on the Chaosnet, as a string (in which case 
the label of unit 0 on that machine is printed, and the user of that machine is notified 
that you arc looking at his label), or, for CADRs only, die string "CC" (which prints the 
label of unit 0 of the machine connected to this machine’s debugging hardware). 

Use of "CC" as the unit is the way to examine or fix up the label of a machine which 
cannot work because of problems wiUi the label. On a Lambda, this must be done 
through the SDU. 

set-current-band partition-name &opdonal (unitO) 

Sets the current saved Lisp image partition to be partition-name. If partition-name is a 
number, the name LOD« is used. 

unit can be a disk drive number, the host name of another Lisp Machine, or the string 
"CC". See die comments under print-disk-label, above. 

If the partition you specify goes with a veision of microcode different from the one that is 
current, this ftinction offers to select the an appropriate microcode partition as well. 
Normally you should answer Y. 

set-current-mlcroload partition-name &optional (unitO) 

Sets the current microcode partition to be partition-name. If partition-name is a number, 
the name MCR« is used. 

unit can be a disk drive number, the host name of another Lisp Machine, or the string 
"CC". See the comments under print-disk-label, above. 
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si:current-band &optional (uniiO) 
si rcurrent-microload &optionaI {uniiO) 

Return, respectively, tlic name of the current band and the current microload on the 
specified unit 

When using tlie functions to set the current load partitions, be extra sure that you are 
specifying the correct partition. Having done it. cold-booting tlie machine will reload from those 
partitions. Some versions of the mienKode will not work with some versions of tlie l isp system, 
and if you set the two current partitions incompatibly, cold-booting the machine will fail, 'lb fix 
this, on a CADR, use another CADR’s debugging hardware, running print-disk-label and set- 
current-band on the other CADR and giving "CC" as the unii argument. On a Lambda, tliis is 
done via the SDU. 

si tedit-dlsk-label unit &optional imi-p 

Runs an interactive label editor on tlie specified unit 'Ibis editor allows you to change 
any field in tlie label. Ibe Help key documents the commands. You have to be an 
expert to need this and to understand what it does, so the commands arc not documented 
here. Ask someone if you need help. You can screw yourself very badly with this 
function. 

disk-restore &optional partition 

Allows booting from a band other tlian the current one. partition may be the name or 
the number of a disk partition containing a virtual-memory load, or nil or omitted, 
meaning to use the current partition, 'Ibc specified partition is copied into the paging 
area of the disk and then started. 

Although you can use tliis to boot a different Lisp image than the installed one, this does 
not provide a way to boot a different microcode image, disk-restore brings up the new 
band with the currently running microcode. 

disk-restore asks the user for confirmation before doing it, 

describe-partition partition &optional unit 

I'clls you various useful tilings about a partition; including where on disk the partition 
begins, and how long it is. 

If you specify a saved Lisp system partition, such as LOD3, it also tells you important 
information about the contents of the partition: tlie microcode version which the partition 
goes with, the size of the data in the partition and tlie highest virtual address used. 'The 
size of the partition tells how large a partition you need to make a copy of this one, and 
the highest virtual address used (which is measured in units of disk blocks) tells you how 
large a PAGE partition you need in order to run this partition. 
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35.11.2 Updating Software 

Of all the procedures described in this section, Uie most common one is to take a partition 
containing a Lisp image, update it to have all the latest patches (see section 28.8, page 672), and 
save it away in a disk partition. The function load-and-save-patches docs it all conveniently 
for you. 

load-and-save-patches 

Loads patches and saves a band, with a simple user intcrfiicc. Run this function 
immediately alter cold booting, without logging in first; it logs in automatically as LISPM 
(or whatever is specified in die site files). The first thing it docs is print the list of disk 
partitions and ask you which one to save in. Answer LOD>;, using the name of a 
partition from tlic printed list. You must then confirm. Then the patches are loaded and 
tlic resulting world is saved with no further user interaction, as long as no problem arises. 

It is convenient to use this function just before you depart, allowing it to finish 
unattended. 

If you wish to do something other titan loading all and only the latest patches, you must 
perform the steps by hand. SUirt by cOld-booting the machine, to get a fresh, empty system. 
Next, you must log in as something whose INLL file docs not affect the Lisp world noticably (so 
that when you save away the Lisp image, tlic side-effects of tlic IN 11’ file won’t get saved too); 
on Mll'-OZ, for example, you can log in as LISPM with password LISPM. Now you can load in 
any new software you want; usually you should also do (load-patches) for good measure. You 
may also want to call shset-system-status to change tlie release status of the system. 

When you’re done loading everything, do (print-disk-label) to find a band in which to save 
your new Lisp world. It is best not to reuse the current band, since if something goes wrong 
during the saving of the partition, while you have written, say, half of tlte band that is current, 
it may be impossible to cold-boot the machine. Once you have found the partition, you use the 
disk-save function to save everything into that partition. 

disk-save partition-name &optional no-query incremental 

Saves the current Lisp world in the designated partition, partition-name may be a 
partition name (a string), or it may be a number in which case the name LOD« is used. 

The user is first asked for yes-or-no confirmation that he really wants to reuse the named 
partition. A non-nil value for no-query prevents this question. I’his is only for callers that 
have already asked. 

Next it is necessary to figure out what to put into the textual description of the band, for 
the disk label. I’his starts with the brief version of si:system-version-info (see page 
674). Then comes a string of additional information; if no-query is nil, the user is offered 
the chance to provide a new string, ’fhe current value of this string is returned by 
si:system-version-info and printed by booting. I'he version info and the string both go 
in the comment field of the disk label for this band. If they don’t together fit into the 
fixed size available, the user is asked to retype the whole thing (the version info as well 
as your comment) in a compressed form that docs fit 
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The Lisp environment is then saved away into the designated partition, and tlicn the 
equivalent of a cold-boot from that partition is done. 

Once the patched system has been successfully saved and the system comes back up, you can 
make it current with set-current-bawd; 

When you do a disk-save, it may tell you tltat the band you wish to save in is not big 
enough to hold all the data in your current world. It may be possible for you to reduce the si/e 
of die daui so that it will fit in tliat band, by garbage collecting. Simply do (sirfull-gc). 

fry to avoid saving patched systems after running the editor or tlic compiler. 'ITiis works, but 
it makes the saved system a lot bigger. In order to produce a clean saved environment, you 
should try to do as little as possible between tlic time you cold-boot and the time you save the 
partition. 

s1: login-history Variable 

The value of sidogin-history is a list of entries, one for each person who has logged into 
tliis world since it was created. This makes it possible to tell who disk-saved a band 
with something broken in it. Hach entry is a list of the user ID, the host logged into, 
the Lisp Machine on which the world was being executed, and the date and time. 

35.11.3 Saving Personal Software 

If you have a large application system which takes a while to load, you may wish to save a 
band containing it. 

To do this, boot a fresh band, log in without running your init file, do make-system to 
load the application system, and then invoke disk-save. When disk-save asks for an additional 
comment, give your name or the name of the application system you loaded, and a date. This 
will tell other people who to ask whether the band is still in use if they would like to save other 
things. 

You can greatly reduce the amount of disk space needed for the saved band by making it an 
incremental band; that is, a band which contains tlic differences between the Lisp world you want 
to save and the system band you originally loaded. Since all the pages of the system which your 
application program did not change do not have to be saved, an incremental band is generally 
much smaller—perhaps by a factor of ten. 

To make an incremental band, give a non-nil third argument to disk-save, as in 
(disk-save "lod4" nil t) 

Figuring out which pages need to be saved in the incremental band takes a couple of extra 
minutes. 

You can restore the incremental band with disk-restore or boot it like any other band. This 
works by first booting the original band and then copying in the differences that the incremental 
band records. It takes only a little longer than booting the original system band. 
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The original band lo which an incremental band refers must be a complete load. When you 
update a standard system band (loading patches, for instance) you should always make a complete 
load, so tliat die previous system band is not needed for die new one to function. 

I'he incremental band records the partition name of die original system band. That original 
band must still exist, with the same contents,, in order for the incremental band to work properly. 
The incremental band contains some error check daut which is used to verify this. The error 
checking is done by the microcode when the incremental band is booted, but it is also done by 
set-current-band, so diat you arc not permitted to select an incremental band if it is not going 
to work. 

When using incremental bands, it is important to preserve die system bands that dicy depend 
on. Therefore, system bands should not be updated too frequently, describe-partition on an 
incremental band says which full band it depends on; you can use diis to detennine which bands 
should be kept for die sake of incremental bands that depend on dtem. 

In order to realize the maximum savings in disk space possible because of incremental bands, 
you must make the partition you saved in smaller once the save is finished and you know how 
much space was actually used. This is done with si:edit-disk-label. The excess space at the end 
of the partition can be used to make another partition which is used for the next incremental 
band saved. Eventually when some of the incremental bands are no longer needed the rest must 
be shuffled so that the free space can be put together into larger partitions. This can be done 
with si:copy-disk-partition. 

An easier technique is to divide a couple of the initial parUtions into several equal-sized 
partitions of about 4000 pages, and use these for all incremental saving. You can easily provide 
room for 12 incremental bands this way in addidon to a few system bands and file system. 

You must not do a garbage collection to reduce the size of the world before you make an an 
incremental band. This is because garbage collection alters so many pages that an incremental 
band would be as big as a complete band. 

35.11.4 Copying Bands 

The normal way to install new software on a machine is to copy the microcode and world 
load bands from another machine. 

The first step is to find a machine that is not in use and has the desired system. Let us call 
this the source machine. The machine where the new system is to be installed is the target 
machine. You can use finger to see which machines are free, and use print-disk-label with an 
argument to examine the label of that machine’s disk and see if it has the system you want. 

Then you should do a (print-disk-label) to find suitable partitions to copy them into. It is 
advisable not to copy them into the selected partitions; if you did that, and the machine crashed 
in the middle, you would be unable to boot it. 

Before copying a band from another machine, double-check the partition names by printing 
the labels of both machines, and make sure no one is using the other machine. Also double¬ 
check with describe-partition that the world load and microcode go together, 'fhen use this 
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function: 

si: receive-band source-host source-band target-band &optional subset-start subset-size 

Copies the partition on source-host "partition named source-band onto die local machine’s 
partition named target-band. 'This Uikcs about ten minutes. It types out die size of the 
partition in pages, and types a number every 100 pages telling how far it has gotten. It 
displays an entry in die who line on die remote machine saying what’s going on. 

The subset-start and subset-size arguments can be used to transfer only part of a partition. 
They arc measured in blocks. The default for die first is zero, and die default for the 
second is to continue to die end of the daui in die band. These arguments arc useful for 
restarting a transfer that was aborted due to network problems or a crash, based on the 
count of hundreds of blocks that was printed out before the crash. 

To go the other direction, use si:transmit-band. 

si: transmlt-band source-band target-host target-band SLoptiona] subset-start subset-size 

This is just like si;receive-band, except you use it on the source machine instead of the 
target machine. It copies the local machine’s partition named source-band onto target- 
machine's partition named target-band. 

It is preferable to use si:receive-band so that you are present at the machine being 
written on. 

After transferring the band, it is good practice to make sure diat it really was copied 
successfully by comparing the original and the copy. All of the known reasons for errors during 
band transfer have (of course) been corrected, but peace of mind is valuable. If the copy was not 
perfectly faithful, you might not find out about it until a long Umc later, when you use whatever 
part of die system that had not been copied properly. 

si: compare-band source-host source-band target-band &optional subset-start subset-size 

This is like si:receive-band, except diat it docs not change anything. It compares the 
two bands and complains about any differences. 

Having gotten the current microcode load and system load copied into partitions on your 
machine, you can make them current for booting using set-current-band. 


35.12 Site Options and Host Table 

The Lisp Machine system has options that are set at each site. ITiese include the network 
addresses of other hosts, which hosts have file servers, which host to find the system source files 
and patch files on, where to send bug reports, what timezone the site is located in, and many 
other things. 

The per-site information is defined by three files: SYS: SITE; SITE LISP, SYS: SITE; 
LMLOCS LISP, and SYS: CHAOS; HOSTS TXT. 
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SYS: CHAOS: HOSTS TXT is tlie network host table. It gives die names and addresses of 
all hosts tliat are to be known to tlte l.isp Machine for any purposes. It also s:iys what type of 
machine tlic host is, and what operating system runs on it. 

SYS: SITE; LMLOCS LISP specifics various information about tlic Lisp Machines at your 
site, including its name, where it is physically located, and what the default machine for logging 
in should be. 

SYS: SITE; SITE LISP specifics all other site-specific infonnation. Primarily, this is 
contained in a call to the special fonn defsite. 

defslte site-name {site-option value)... Macro 

'This special fonn defines die values of site-specific options, and also gives the name of 
die site. H.ach site-option is a symbol, normally in die keyword package, which is die 
name of some site option, value is the value for diat option: it is evaluated. Here is a 
list of suindardly defined site options: 

:sys-host The value is a string, the name of the host on which the system source 
files arc stored. 'Phis host becomes die translation of logical host SYS. 

:sys-host-translation-alist 

The value is an alist mapping host names into translation-list variables. 
Each translation list variable’s value should be an alist suitable for being 
the diird argument to fs:add-logical-pathname-host (see page 574). 
The car of an clement may be nil instead of a host name; then this 
element applies to all hosts not mentioned. 

The normal place to find the system sources is on the host specified by 
the :sys-host keyword, in the directories specified by the translation list 
variable found by looking that host up in the value of the :sys-host- 
translation-alist keyword. If you specify a different host as the system 
host with si:set-sys-host, that host is also looked up in this alist to find 
out what directories to use there. 

Here is what is used at MIT: 

(defsite rmit 

(:sys-host-translation-a1ist 

’(("AI” . its-sys-pathname-tfanslations) 

("OZ" . oz-sys-pathname-translations) 

("FS" . its-sys-pathname-translations) 

("LM" . its-sys-pathname-translations) 

(nil . its-sys-pathname-translations))) 

...) 
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(defconst oz-sys-pathname-translations 
’(("CC;" "<L.CC>") 

("CHAOS;" "<L.CHA0S>") 

("DEMO;" "<L.DEM0>") 

("SITE;" "<L.SITE>") 

("SYS;" "<L.SYS>") 

("SYS2;" "<L.SYS2>") 

("ZMAIL;" "<L.ZMAIL>") 

("ZWEI;" "<L.ZWEI>") 

)) 

;sys-login-name 
:sys - logi n - password 

TTtese specify the username and password to use to log in automatically to 
read system patch files, microcode symbol tables and error tables. The 
values should be strings. 

:chaos nil if the site has no Chaosnet; otherwise, a string, the name of the 

Chaosnet that the site is on. Names for Chaosnets will eventually be used 
to permit communication between Chaosnets, probably through special 
gateway servers. Except when multiple sites are on a single Chaosnet, 
normally the Chaosnet name should be the same as the site name (but as 
a string, not a symbol). 

:standalone The value should be t for a Idsp Machine that is operated without a 
network connection. This causes the Lisp Machine to not to try to use 
the Chaosnet for getting the time. On the I.ambda, the time will obtained 
from the SDU’s clock. On the CADR, the time will be obtained from 
the user. 

idefault - associated - machine 

'This should be a string which is the name of a host to use as the 
associated host for any Lisp Machine not mentioned in the LMLOCS file. 

:usual-lm-name-prefix v; 

'This should be a string which is the typical beginning of host names of 
Lisp Machines at your site. At MIT, it is "CADR-". 

:chaos-file-server-hosts 

This should be a list of names of hosts that have file servers, including 
Lisp Machines which other Lisp Machines should know about 

:lmfile-server-hosts 

This should be a list of names of Lisp Machines that provide servers for 
the LMFILE file system, 'fhe entry for such a machine should be one of 
the nicknames of that machine. By virtue of its presence in this list it 
becomes the name by which the LMFILE file system there can be 
accessed remotely. 

:chaos-time-server-hosts 

TTiis should be a list of names of hosts that support TIME servers. These 
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arc hosts that the Lisp Machine can ask die time of day from when you 
. boot. 

:chaos-host-table-server-hosts 

'I'his should be a list of names of hosts that support host-table servers, 
which can be used to inquire about hosts on networks that the Lisp 
Machine docs not know about in its own host table. 

:chaos-mail-server-hosts 

Hiis should be a list of names of hosts that support mail servers which 
are capable of forwarding mail to any known host. 

itimezone I'his should be a number, the number of hours earlier tlian GMT of 
standard time in the timezonc where this site is located. 

:host-for-bug-reports 

I'his should be a string, the name of the host at which bug-report 
mailboxes are located, 

:local-mail-hosts 

This should be a list of names of hosts that ZMail should consider local 
and omit from its summary display. 

:spell-server-hosts 

This should be a list of hosts that have spelling corrector servers. 

xomsat This should be t if mail can be sent through the COMSAT mail demon. 
This is true only at MIT. 

;default-mail-mode 

This should be the default mode for use in sending mail. The options are 
:file (use COMSAT). :chaos (use one of the :chaos-mail-server-hosts), 
or :chaos-direct (like xhaos, but go direct to the host that the mail is 
addressed to whenever possible). 

-.grnsgs I'his should be t if GMSGS servers are available. 

:arpa-gateways 

This should be a list of names of hosts that can be used as gateways to 
the Arpanet These hosts must provide a suitable Chaosnet server which 
will make Arpanet connections. It should be nil if your site does not have 
an Arpanet connection. 

:arpa-contact-name 

If you have Arpanet gateways, this is the Chaosnet contact name to use. 
Nowadays, it should be "TCP". 

;dover This should be t if your site has a Dover printer. 

:default-printer 

This should be a keyword which describes the default printer for hardcopy 
commands and functions to use. Possible values include :dover, nil, or 
any other printer type that you define (see section 35.2, page 785). 

:c!efault-bit-array-printer 

Like :default-printer, but this is the default for only hardcopy-bit-array 
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to use. 

:esc-f-arg-aHst 

This says what various numeric arguments to the Terminal F command 
mean. It is a list of elements, one for each possible argument. The car 
of an clement is cither a number or nil (which applies to Terminal F with 
no argument). ITie edr is cither ;login (finger the login host), lisp- 
machines (finger all Lisp Machines at this site), :read (read some hosts 
from the keyboard), or a list of host names. 

:verify-lm-dumps 

If the value is t. Lisp Machine file system dump tapes are verified. 

Other site options are allowed, and your own software can look for them. 


35.12.1 Updating Site Information 

To update the site files, you must first recompile the sources. Do this by 
(make-system ’site ’compile) 

This also loads the site files. 

To just load the site files, assuming they are compiled, do 
(make-system ’site) 

load-patches does that automatically. 

You should never toad any site file directly. All the files must be loaded in the proper 

fashion and sequence, or the machine may stop working. 

35.12.2 Accessing Site Options 

Programs examine the site options using these variables and functions: 

site-name Variable 

The value of this variable is the name of the site you are running at, as defined in the 
defsite in the SITE file. You can use this in run-time conditionals for various sites. 

get-site-option keyword 

Returns the value of the site option keyword, llie value is nil if keyword is not 
mentioned in the SITE file. 

defIne-site-varlable variable keyword [documentation] Macro 

Defines a variable named variable whose value is always the same as that of the site 
option keyword. When new site files are loaded, the variable’s value is updated. 
documentation is the variable’s documentation string, as in defvar. 
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def 1ne-site-host-l 1st variable keyword {documentation] Macro 

Defines a variable named variable whose value is a list of host objects specified by the site 
option keyword. The value actually specified in the SITE file should be a list of host 
names. When new site flics are loaded, the variable’s value is updated, documentation is 
the variable’s documentation string, as in defvar. 

35.12.3 The LMLOGS File 

'Fhc LMLOCS file contains an entry for each Lisp Machine at your site, and tells tlie system 
whatever it needs to know about the particular machine it is running on. It contains one form, a 
defconst for ilic variable machine-location-alist. The value should have an clement for each 
Lisp Machine, of this form: 

("MIT-LISPM-1" "Lisp Machine One" 

"907 [Son of CONS] CADRl’s Room x6765" 

(MIT-NE43 9) "OZ" ((:default-printer :dover))) 

I’he general pattern is 

( host-full-name pretty name 
location-string 

(building floor) associated-machine site-options) 

The host-full-name is the same as in the host table. 

The prettyname is simply for printing out for users on certain occasions. 

The location-string should say where to find the machine’s console, preferably with a 
telephone number, lliis is for the FINGER server to provide to other hosts. 

The building and floor are a somewhat machine-understandable version of the location. 

The associated-machine is the default file server host name for login on this Lisp Machine. 

site-options is a list of site options, just like what goes in the defsite. 'Hiese site Options 
apply only to the particular machine, overriding what is present in tlie SITE file. In our example, 
the site option :default-printer is specified as being :dover, on this machine only. 

s1: associated-machine Variable 

TTie host object for the associated machine of this Lisp Machine. 
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stream .. 448,4.59 

.string. 12,163.203 

structured pathname components.,549 

structures.. . 372 

subprimitivc . .. 270 

subscript.162 

subst.. 230,329 

substitutable function.329 

substitution. 97 

supplied-p variable. 42 

.symbol.. 9.11.129 

system ..660 

system maintenance. 672 

tag..78,80 

tail recursion.55 

Tencx pathnames. 570 

terminating macro character.540 

terminating the iteration 

in loop..358 

throw.80 

limes and dates.776 

TOPS-20 pathnames. 569 

total size of an array.' . . 162 

tracing function execution.737 

traditional syntax. 507,516 

transformation.663 

tree. 86 

Twenex pathnames.569 

type (pathname). .547 


type specifiers. .14 

types of arrays. .163 

unbinding . .... . 25 

unbound variable. 26 

uninicrned symbol. 133 

universal time.776 

Unix pathnames. .570 

unreleased patches . .. .677 

unspecific pathname components.548 

uiity ped methods. ..434 

unwind protection.82 

unwinding a stack. 82 

upper cjtse letter.212 

value cell.29,129 

variable bindings 

in loop.• • • .354 

vector.162 

version (pathname). .547 

very mangled software. . ..570 

V.MS pathnames ..570 

void binding.26 

wait.682 

wait function.683 

warnings from the compiler.308 

wildcards (in pathnames)..563 

yes-or-no.768 

’ &' keywords.43 
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Flavor Index 


condition. 705 

error .. 705 

Terror .. 706 

fs: file-error. 604 

siibidireclional-slrcam. 475 

si:btiffered-charactor-slrcam. ........... 478 

si:buffered-input-characler-slrcam..478 

si:buffered-input-slreani . ...476 

si:buffered-oulpiit-characler-siream ........ 478 

siibuffered-oulpul-stream.476 

si;buffered-slrcam.477 

si:file-stream-mixin. 479 

si:inpul-file-slreain-mixin. 479 

si:inpiit-pointor-remembcring-mixin.. . 478 

si:input-stream...475 

si:linc-oulpul-.stream-mixin.. 477 

si:oulpul-file-streani-mixin.. . 479 

si;oulput-i)oinlcr-rcmcmbcring-mixin. . ..478 


si:output-stream. 475 

si:print-rcadably-mixin . . .. 446 

si:proress. 695 

.si:property-list-mixin. 445 

si:siniple-proces.s..695 

,si:strcam...475 

si:unbuffcrcd-line-input-stream..477 

si: vanilla-flavor ..432 

sys:bad-array-niixin. 173.706 

sy.s:cell-contents-error. .60 

sys:local-nelwork-crror. 623 

.s>'.s:network-crror.. 622 

sys:no-aclion-mixin...705 

sys:proceed-with-value-mixin.706 

sys:redefinition. .. 240 

sys:remotc-network-error.. . 623 

sysiwaming. 706 
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Operation Index 


:acccpt 

(on chaos:basic-strcam).618 

:activc-p 

(on si: process).694 

:advancc-input-buffcr 

(on streams).... . 470 

:any-tyi 

(on streams).461 

:any-t>i-no-hang 

(on streams).467 

:arrest-reason 

(on si;proccss)..694 

:arrcst-rcasons 

(on si:process).694 

:back-translated-pathname 

(on fs:logical-pathnamc).574 

:beep 

(on streams). 467 

:break ..433 

:bug - report-description 

(on condition)..707 

:bug - report-recipient-system 

(on condition).707 

:canonical-type 

(on pathname)... . SS2 

:changc-properties 

(on pathname). ..593 

tcharacters 

(on streams).465 

;clear-eof 

(on chaos:basic-input-stream). 618 

:clear-hash 

(on hash-table).120 

:clcar-input 

(on streams).469 

:clear-output 

(on streams).469 

.•dear-screen 

(on streams).. . 468 

:close 

(on streams). 463,464 

(on chaos:basic-stream) ..618 

:close-all-files 

(on host objects).579 

:complcte-string 

(on pathname).593 

:condition-names 

(on condition). 700 

:cpu-time 

(on sitproccss).693 

tcreate-directwy 

(on pathname).594 


:crcation-datc 

(on file streams).. . ..588 

:dangerous-condition-p 

(on condition). . ..706 

:dcbuggcr-conimand-loop 

(on condition). .708 

:dcbugging-condition-p 

(on condition). .. .706 

idelctc 

(on pathname). 593 

(on file streams).. 588 

.‘describe. 432 

:device 

(on pathname).550 

:device-wild-p 

(on pathname) ..564 

: direction 

(on streams) .. 465 

:dircctoty 

(on pathname).550 

:dircctory-1ist 

(on pathname).594 

:directory-pathname-as-file 

(on pathname) ..567 

:directory-wild-p 

(on pathname).'.564 

tdiscard-inpul-buffer 

(on si:buffered-input-strcam).476 

: discard - output-bu ffer 

(on si:buffcrcd-output-stream).477 

:disk-wait-time 

(on sitprocess).693 

: document- procccd-xype 

(on condition).719 

:elcment-type 

(on streams).465 

:eof 

(on streams).464 

(on chaos:basic-output-stream) ..618 

:eval-inside-yourself . ..433 

lexpunge 

(on pathname).594 

:fasd-form 

(on instances). .. 317 

:fillcd-entries 

(on hash-table).120 

:find-current-frame 

(on condition).707 

lOnish 

(on streams). 469 
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(on chaos:basic-oulpul-strcam).. . 618 

;flush , 

(on si:proccss) ... 

:fnl 

(on its-pathnamc) . ... . 569 

:fn2 

(on iis-pathnaine) . ...569 

:forcc-output 

(on streams). .469 

(on chaosrbasic-output-sircam).(>18 

; force-rescan 

(on streams)..502 

:foreign-host 

(on chaos:basic-stream).. .618 

:frcsh-linc 

(on streams). 464 

:funcall-insidc-yoursclf. .. 433 

;generic-basc-type 

(on host objects). 579 

:gcneric-pathname 

(on pathname). 563 

(on file streams).'587 

:gel 

(on si;propcrty-list-mixin).445 

(on pathname).567 

:gct-handler-for.432 

:gct-hash 

(on hash-table). ... . 120 

tgct-inpul-bufTer 

(on streams)..469 

:get-location 

(onsi:property-list-mixin).. . 445 

;get-location-or-nil 

(onsi:property-list-mixin) . ..445 

:get-old-data 


(on sitoutput-pointer-remembering-mixin).479 

:getl 

(on si:property-list-mixin) ............ 445 

(on pathname). .567 

:host 

(on pathname).550 

:idlc-time 

(on si:process)..• • • • 

:incremcnt-cursotpos 

(on streams)..467 

:info 


(on file streams) ..588 

:init 

(on all flavor instances). 418 

:initial-form 

(on si:process). 692 

:initial-slack-group 

(on si: process).692 


:interrupt 

(on si: process). 

:kill 

....... 695 

....... 695 

:length 

(on file streams). 

. ..587 

:line-in 

(on streams). .. 

....... 462 

:line-out 

(on streams). .......... 

. ..464 

•.listen 

(on streams). . . . . . . . . . . 

.466 

:map-hash 

(on h.ish-table) . ... . 

.120 

:map-hash-rctum 

(on hash-table) ......... 

.120 

:maybe-clear-inpitt 
(on condition)... 

...... .707 

:modify-hash 

(on hash-table). 

. .120 

:name 

(on si:proccss)... 


(on pathname). 


(on host objects).. 

.578 

:name-as-rilc-computer 
(on host objects). 

....... 578 

':name-wild^p 

(on pathname).. 

.564 

:network-addresses 
(on host objects). 

.578 

:nclwork-type 

(on host objects).. • 


:network-typep 

(on host objects). 


:new-canonical-type 
(on pathname). 


:new-device 

(on pathname). 

.550 

;new-direaoiy 

(on pathname).. 

.550 

:new-name 

(on pathname). .. 

.550 

:new-output-bulTer 
(on si:buffered-output-stream). . . 

....... 476 

:new-pathname 

(on pathname). . ... . 

. .551 

: new-raw-device 

(on pathname). 

.550 

:ncw-raw-directory 
(on pathname). 

.550 

:ncw-raw-name 

(on pathname). 

.550 

:new-raw-type 

(on pathname). ......... 


:ncw-suggcsted-dircctory 
(on pathname). 

.551 

:new-suggesied-name 
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(on pathname). 551 

:ncw-iype 

(on pathname). 5.50 

: new - tyi>e-and-version 

(onpatlmame). .. .569 

:new-version 

(on pathname). ...550 

aiext-inpul-bulTcr 

(on sirbuffcrcd-inpiit-stream).476 

:opcn 

(on pathname). ...593 

aipcn-canonical-dcfault-lypc 

(on pathname).. 554 

:opcn-strcams 

(oil host objects).579 

:opcration-handlcd-p.432 

:opcration-handled-p 

(on streams).465 

arathname 

(on file streams). 587 

:pathname-as-direclory 

(on pathname). . ..567 

•.pathname-host-namep 

(on host objects).578 

:pathnamc-match 

(on pathname).564 

:perccnt-utilization 

(on si:proces$). .693 

:plist 

(on pathname). 567 

rpreset 

(onsirprocess).694 

tpiimary-device 

(on pathname). ..563 

:prinl-error-message 

(on condition).707 

:print-self. 432 

tpriority 

(on sitprocess) .. .693 

:procccd-asking-user . 

(on condition).719 

:procecd-type-p 

(on condition).718 

:procccd-types 

(on condition).718 

tproperties 

(on pathname). 594 

(on file streams) .. 588 

:property-list 

(on si:propetly-list-mixin).. 446 

:propcrty-list-location 

(on si:propcrty-list-mixin). 446 

:push-property 


(on si:propcrty-lLst-mixin).445 

:put-hash 

(on h.ash-tablc). .120 

iputprop 

(on si:propcrty-list-mixin) . ..445 

(on pathname). 567 

tqfaslp 

(on file streams)... . ..587 

tquantum 

(on siiprocess). 692 

iquantum-remaining 

(on si;proccss). 693 

:raw-dcvicc 

(on pathname).550 

;raw-dircctory 

(on pathname).550 

:raw-name 

(on pathname) ..550 

:raw-type 

(on pathname).550 

:read-bp 

(on streams) ..502 

;read-cursorpos 

(on streams).467 

tread-input-buffer 

(on streams) ..469 

tread-pointer 

(on streams).468 

tread-until-eof 

(on streams).. . .463 

treconstruction-init-plist 

(on sitprint-rcadably-mixin). ..446 

trcject 

(on chaostbasic-stream). .618 

trem-hash 

(on hash-table).. . .120 

tremote-connect 

(on pathname).594 

tremprop 

(on sitproperty-list-mixin) ..445 

(on pathname).567 

trename 

(on pathname).593 

(on file streams).588 

treport 

(on condition).706 

treport-string 

(on condition).706 

trescanning-p 

(on streams). 502 

treset 

(on sitprocess).694 

tresel-meters 

(on sitprocess).694 

trevoke-arrest-reason 

(on sitprocess) . ^..694 

trevoke-run-reason 
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(on si:proccss). 

ircwind 

(on streams)..• • • 

:ruboul-handlcr 

(on streams).. 

:run-reason 

(on si:proccs.s) ... 

:run-reasons 

(on siiproccss) . . . . . . ... • • • 
:runnable-p 

(on sitproccss) ... . . 

isamplc-pathnamc 

(on host objects) ... . . 

:scnd-if-handlcs.. 

:scnd-if-handles 

(on streams).. 

;send-output-buffer 

(on si:buffercd-output-strcam). 

:set... 


:scl*bufTer-pointer 

(on si:output-pointcr-remcmbering-mixin) 
(on si:input-pointer-rcmcmbering-mixin). 
:sct-byte-size 

(on file streams) .. 

:set-cursorpos 

(on .streams). 

:sct-pointer 

(on streams).. 

:set-priority 

(on si:process).. . . . 

iset-propcity-list 

(on si;property-list-mixin). 

:sct-quantum 

(on si:process).. . . 

:sct-wami-boot-action 

(on si:process). 

:short-name 

(on host objects). 

:simple-p 

(on si:process). 

:size 

(on hash-table). . .. 

:source-pathname 

(on pathname) .. 

:stack-group 

(on si:process). 

:string- for-directory 

(on pathname). 

:st ring-for-dired 

(on pathname). 

:string-for-editor 

(on pathname). 

:siring-for-host 


. . 694 

(on pathname). . 


:string-for-printing 

. . 469 

(on pathname). . 


;string-for-wholinc 

467. 502 

(on pathname). . 


;string-in 

. . 694 (on .streams). . . . . 

:string-linc-in 

, . 694 (on .streams). 

:string-out 

. . 694 (on streams). .... 
:swap-hash 

. . 578 (on hasli-table) . . . 

:systcm-type 

. . 433 (on host objects)... 

:total-nin-iime 
(on si:process). ... 

. . 465 :translatc-wild-pathname 

(on pathname). . . . 

. . 477 :iranslated-pathname 

(on fstlogical-pathname) 

, . 432 :trucname 

(on pathname). . . . 
(on file streams) . . . 

. . 478 :tyi 

. . 478 (on streams). 

:tyi-no-hang 

. . 588 (on streams). 

:tyipcek 

. . 468 (on streams). .... 

:tyo 

. . 468 (on streams). .... 

:type 

. . 693 (onpathname). . .. 

:type-and-version 

. . 446 (on pathname). . . . 

:type-wild-p 

. . 692 (on pathname). . . . 

:undeletablc-p 

. . 693 (onpathname). . . . 

tundelete 

. . 578 (on pathname). . . . 

(on file streams) . . . 

. . 693 :untyi 

(on streams). 

. . 120 :untyo 

(on streams). 

. . 563 :untyo-mark 

(on streams). 

. . 692 :user-proceed-types 

(on condition).... 

. . 567 :vcrsion 

(on pathname). . . . 

. . 567 :version-wild-p 

(on pathname). . . . 

. .566 :wait-argumcnt-list 

(on si'proeess). . . . 


567 

566 

566 

462 

463 

464 
120 
578 
693 
565 
574 

592 

587 

461 

466 

461 

463 

550 

569 

564 

593 

593 

588 

461 

468 

468 

720 

550 

564 

692 
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:wail-funclion 
(on si:process). . 

: \va nil- b(x>l -action 
(on si:process). . 

:w hich-operations. 


692 

693 
432 


(on streams) . 
:whostatc 
(on si'.process) 
:wild-p 
(on pathname) 
•.wildcard-map 
(on pathname) 


,465 

.692 

.564 

.594 


:which-operations 
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:abslracl-flavor 

(for dcfflavor).... , .428 

:acccssor-prcfix 

(fordcfflavor), ................ 428 

:aclual-si/.c 

(formake-cqual-hash-table) . ..119 

;adjusiablc-p 

(for make-array) ..169 

:alias-flavor 

(for dcfflavor). 428 

:allow-olhcr-key.s 

(for keyword arguments)^ ...40 

:altcranl 

(fordcfstruct). ..378 

chaos:answercd-slate 

(for conneciion s(atc).614 

:area 

(formake-cqual-hash-table)..118 

(for make-array). 168 

:arg 

(for trace). 739 

:argpdl 

(for trace).739 

:arpa-contact-name 

(for defsite).813 

:arpa-gatcways 

(for defsite).. .... 813 

larray 

(fordcfstruct). 376 

:array-leadcr 

(for defstrua) ..,377 

:arrest-reasons 

(for make-process).690 

;batch 

(for make-system). 667 

:beep 

(forfquery).769 

:both 

(for trace). 739 

:break 

(for trace).738 

:but-first 

(for defsiruct).383 

:byte-size 

(for open) .. . 583 

:callablc-accessors 

(fordcfstruct) . ..383 

;callable-constructors 

(fordcfstruct).383 

:chaos 

(for si:sb-on).687 

(for defsite).812 


:chaos-file-server-hosts 

(for defsite). .. 812 

:chaos-host-table-scrvcr-hosls 

(for defsite). 813 

:chaos-mail-scrver-host.s 

(for defsite), . .... . 813 

xhaos-time-server-hosts 

(for defsite). 812 

xharacter 

(for prompt-and-read). 454 

rcharacters 

(for open) . ..583 

xhccker 

(for dcfresource)..125 

xhoices 

(for fquery). .. 769 

xlcar-input 

(for fquery). 769 

xloclc 

(for si:sb-on) .. 687 

chaos xls-rcceived-state 

(for connectitm state) .. 614 

xomparc-function 

(formake-cqual-hash-table).118 

xompile 

(for make-system). 667 

xomponent-systems 

(for defsystem).661 

:comsat 

(for defsite). 813 

xonc-name 

(fordcfstruct). 379 

:cond 

(for trace) ..739 

xondidon 

(for fquery). 769 

:cons 

(forsi:defstruct-define-type) .......... 397 

:cons-keywords 

(for si:defstruct-defme-typc).398 

xonstructor 

(for dcfresource)..124 

(for defstruct).378 

zweixonvcrse-message-received 

(for beep).457 

zwcixonverse-problem 

(for beep).457 

:copier 

(forsi:defstrucl-dcfine-type).399 

(for defstruct) ..378 
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x'opics 

(for hardcopy-file) . . . . •. 
xopy-modc 

(for fs:balancc-dircctorics) . 
xrcalc-packagc 
(forsys:packagc-not-found) . 
:datc 

(for prompt-and-read) . . . 
:dale-or-ncvcr 
(for prompt-and-read) . . . 
:decimal-nuniber 
(for prompt-and-read) . . . 
:dccimal-iuimbcr-or-nil 
(for prompt-and-read) . . . 
; dc fail It -associated - machine 

(for defsite).. 

•.default-binary-file-type 

(for defsystem). 

;default-bil-array-printcr 

(for defsite). 

:default-handier 

(fordefflavor). 

:dcfault-init-plist 

(fordefflavor) .. 

;default-mail-mode 

(for defsite). 

:default-pointer 

(for defstrua).. 

rdefault-printer 

(for defsite). 

:dcfaulted-baich 

(for make-system). 

tdefstruct 

(for si:defstruct-define-type) 
; defstruct-keywords 
(for si:defstruct-deline-type) 
:deleted 

(for fstcomplete-pathname) . 
(for open) ........ 

(for fs:dire<aory-li.st). . . . 
:delimited-string 
(for prompt-and-read) . . . 
:delimited-string-or-nil 
(for prompt-and-read) . . . 
;direction 

(for fs:baiance-directories). . 

(for open) .. 

rdisplaced-index-offset 

(for make-array). 

:displaced-to 

(for make-array). 

:documentation 
(for defstrua slot option) . . 
(fordefflavor) ...... 

:dover 

(for printer-type). 

(for defsite). 


. 786 

:elemcnt-typc 

(for make-array) . .. 

.168 


:eniry 


. (>04 

(for trace).. 

..... .739 

. 651 

xntrycond 

(for trace).. 

..... .738 


rcntryprinl 


. 454 

(fortrace) . 

.739 

. 454 

rerror 

(fortrace). 

.738 


(for open).. 

.585 

. 4.54 

(for fstbalance-dircctories). 

..(i04 

. 454 

:c.sc-f-arg-alist 

(for defsite).. 

.814 

. 812 

:cstimatcd-si/e 

(for open). 

.585 

. 662 

:cval-forai 

(for prompt-and-read). 

..... .453 

. 813 

:cval-form-or-end 

(for prompt-and-read). 

.453 

. 427 

;eva!-scxp 

(for prompt-and-read). 

..... .453 

. 425 

;eval-sexp-or-end 

(for prompt-and-read). 

.453 

. 813 

:exit 

(fortrace).. 

.739 

. 379 

:exitbreak 

(for trace). 

.738 

. 813 

xxitcond 

(fortrace). 

.738 

. 667 

texitprint 

(fortrace)... . 

.739 

. 399 

export 



(for dcfpackage). 

.653 

. 398 

. 602 

.'expression 

(for prompt-and-read). . .. 

.453 

. 585 

:expression-or-end 


. 599 

(for prompt-and-read)........ 

.453 

. 454 

external 

(for intern). 

.645 

. 455 

:fill-pointer 

(for make-array).. . . . 

..169 

. 604 

:find-callers 

(for mctcr:analyze). 

.789 

. 583 

ifinder 



(for dcfresource). . .. 

.125 

. 169 

: first 



(for add-initialization). .. 

..... .774 

. 168 

tfixnum 



(for defstrua).. . . . 

.377 

. 375 

:fixnum-array 


.430 

(for defstrua). 

.377 

. 785 

rflavor 

(for make-process).. . 

.690 


813 (for open).585 
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aiomim-array 

(fordcfstruct). 377 

:roiit 

(forhardcopy-filc) ..785 

: font-list 

(for prompt-and-read) ... ... ..454 

(for hardcopy-file). 785 

iforcc-unfinished 

(for load-patches).. . ... 676 

chaos; foreign-state 

(for connection state) .. 614 

: formal 

(forhardcopy-filc).785 

ifquery 

(for prompt-and-read). 455 

fquery 

(for beep). 458 

:free-list-size 

(for defrcsource) . ..124 

: french 

(for lime:monlh-string).783 

(forlimc:day-of-the-week-slring)..783 

: fresh-line 

(for fquery) ... . 769 

igc 

(for make-area) ..298 

igerman 

(for time:month-string).783 

(for time;day-of-the-weck-siring).783 

:gellable-instance-variablcs 

(for defflavor). . ..424 

:gmsgs 

(fordefsite).813 

:grouped-array 

(for defstrua). 377 

;hash-lunclion 

(for makc-equal-hash-table).118 

:hcading-fonl 

(for hardcopy-file).785 

:height 

(for sys:wilh-hclp-slrcam).473 

:help-(unclion 

(for fquery) .. 769 

:hosl 

(forprompl-and-read) ..455 

chiios;host-down-.slate 

(for conneclion state). 614 

;host-for-bug-reports 

(fordefsite).813 

•.host-list 

(for pronipt-and-read) ..455 


:hosts 

(for loitd-patches) . .675 

:if-cxists 

(for open) .. . 584 

tignore 

(forfs:haIance-dircctorics) ..604 

import 

(for dcfpackage). 653 

import-from 

(for dcfpackage) .. 653 

:in 

(for fstcomplele-palhname). 602 

chaos:inactive-.state 

(for connection state).614 

rincludc 

(fordcfstruct) . .. 379 

tincluded-flavors 

(for defflavor). 426 

tinclusive 

(for meterranalyze)..789 

:incremcnt-patch 

(for makc-systeni). 667 

' inherited 

(for intern).645 

rinit-keywords 

(for defflavor). 425 

;initial-contents 

(for make-array).168 

. tinitial-copies 

(for defresource).. . 124 

:initial-element 

(for make-array). 168 

linitial-offsct 

(fordcfstruct). 383 

:initia)-status 

(for defsystem). 662 

linitial-value 

(for make-array). .168 

linitializer 

(for defresource)..124 

:initlable- instance-variables 

(for defflavor).424 

:instancc-area-flmction 

(for defflavor).429 

tinstantiation- flavor- function 

(for defflavor). 429 

:internal 

(for intern). 645 

invisible 

(for dcfpackage). 652 
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(rorlimcaiJoiuh-striiii}) ......... 

. . . . 78.) 

(for liniciday-of-tlic-wcck-siring) .... 

. ... 78) 

: keyboard 

(forsirsb-on). 

.... ()87 

:kcyword-lisi 

(forproinpt-and-rcad) . ... 

.... 454 

:kcywords 

(for sirdcfstrucl-dcfinc-lypc). 

.... .)98 

: label 

(forsys;wiih-heip-strcam).. 

.... 472 

:lcader-lengih 

(foi make-array).. 

.... Ift8 

:leadcr-list 

(for make-array).. 

.168 

:liiik-to 

(for open). 

. ... 585 

:list 

(fordefstruct).. 

. . . . )76 

:lisi-choiccs 

(for fquery). 

.... 769 

chaos:li.slcning-state 

(for connection state). 

.... 614 

:lmrilc-ser\'cr-hosts 

(for defsite).. 

.... 812 

:local-mail'-hosts 

(for defsite).. 

.... 813 

;logical-volume 

(for open). 

.... 586 

dong 

(fortime:month-string). 

.... 783 

(fortime:day-of-the-week-string) . . . . 

. . . .783 

chaosdos-received-state 
(for connection state). 

.... 614 

:macro 

(for setsyntax). .. 

.... 539 

;make-array 

(fordefstruct).. 

.... 381 

anake-complete 

(for fquery). 

.... 770 

imatcher 

(for dcfresource). 

.... 125 

rmedium 

(for time:!nonth-string).. 

.... 783 

(forlimc:day-of-the-week-string) . . . . 

.... 783 

imcthod-combination 

(for defflavor) ... . 

.... 429 

mixture 

(for defflavor).. 

.... 429 

module 

(for defsystem).. . 

, .... 662 

:nanie 

(for process-run-function). 

, .... 691 


(for defsyslem). 


(for make-area) .. 

;namcd 

(for si;dcfstruct-dcfinc-tyiic). 

(fordefstruct).. 

:nanicd-array 

(fordefstruct) ............ 

aiamed-array-leader 

(fordefstruct) .. 

-.named-fixiium-array 

.... .297 

.... .398 
.... .381 

.... .376 

.377 

.377 

:named- flonum-array 
(fordefstniet). 

.... .377 

aiamed-list 

(fordefstruct). , 

.... .376 

mamcd-stnicturc-symbol 
(for make-array).. 

. . .. .169 

:namcd-typed-array 
(fordefstruct). 

.377 

:named-vector 

(for dcfstruct). 

.377 

: new-name 

(for sys:packagc-not-found). 

. . . , .651 

:ncw-ok 

(for fsxomplcte-pathname). 

.603 

nicknames 

(for dcfpackage).. 

.652 

:no-action 

(forsys:package-not-found). ..... 


zwei;no-completion 

(for beep). 


:no-incremcnt-patch 
(for make-system). 

.667 

:no-pointer 

(for siiprinting-random-object) .... 

.513 

:no-reload-system-declaration 
(for make-,system). 


:no-vanilla-flavor 

(for defflavor). 

.427 

inoconfirm 

(for make-system). 

.666 

inoerror 

(for fs:directory-list).. 

.598 

tnohosts 

(for load-patches). 

.... .675 

:noload 

(for make-system). 


:tiOop 

(for make-system). 

.667 

inormal 

(for add-initialization). 

.774 

:noselective 

(for load-patches). 

.676 


mosite 
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(for load-patches). ... . 

.... 675 

:iiot-in-disk-labcl 

(fordefsystem).. 

.... 662 

tvtnolify 

(forbeep). .. 

. . . . 457 

:now 

(foradd-iniliaii/iilion). 

.... 774 

: number 

(forprompt-:md-rcad). 

.... 453 

:numbcr-of-valucs 

(for makc-cqual-hash-tablc). 

.... 118 

:numbcr-or-nil 

(forprompt-and-read). 

.... 4.54 

told 

(for fstcomplctc-palhnamc). 

.... 603 

chaos:open-state 

(for connection state). 

.... 614 

tordcrcd-instancc-variablcs 
(for defflavor).. . . . 

.... 427 

tout 

(for fstcomplete-pathname). 

.... 602 

touiside-acccssiblc-instance-variables 
(for defflavor). 

... .421 

toverhead 

(for si:dcfstruct-define-type). 

.... 398 

tpackage 

(for defsystem). 

.... 662 

tpage-hcadings 

(for hardcopy-file) .. 

.... 786 

tpast-date 

(forprompt-and-read). 

.... 4.54 

:past-date-or-never 

(forprompt-and-read). 

.... 454 

tpatchable 

(fordefsystem)... . 

.... 662 

tpalhname 

(forprompt-and-read). 

. . . .455 

tpathiiame-dcfault 

(for defsystem). 

.... 662 

tpathnamc-host 

(forprompt-and-rcad). 

. . . .455 

tpathname-list 

(forprompt-and-read). 

. . . .455 

:pathname-or-nil 

(forprompt-and-read). 

.... 455 

tpdl 

(for make-area). 

.... 298 

tphony-namcd-vector 
(for dcfstruct). 

... .211 

tphysical-volume 

(for open). 

.... 586 

tpredicate 

(forsitdcfstruct-dcfine-type). 

.... 399 


(fordcfslruct).378 

prefix-name 

(for derpackage).6S2 

:preser\e-dates 

(for open) . ..585 

;press-filc 

(forprinter-type).785 

:print 

(fordefslrucl) .. 384 

(for trace).739 

(forfsxomplcte-pathname). 602 

:print-only 

(for make-system).667 

rprinter 

(forhardcopy-filc).785 

:priority 

(for process-run- function).691 

(for make-process).690 

:propcrty 

(for dcfstrucl).383 

tquantum 

(forproccss-run-function).691 

(for make-process).690 

:qucry-mode 

(for fs:balance-dircctories).604 

:raw 

(for open).586 

tread 

(forprompt-and-rcad).453 

(for fstcomplcte-paihname).602 

:rcad-only 

(for make-area).298 

(for defslruct slot option).375 

recompile 

(for make-system).667 

:redo 

(for add-initialization). 774 

:ref 

(forsi:dcfstruct-dcfine-type).397 

:region-size 

(for make-area).297 

:regular-pdl-area 

(for make-stack-group). 259 

(for make-process).690 

:rcgular-pdl-size 

(for makc-stack-group).259 

(for make-process).690 

:rchash-bcforc-cold 

(for make-equal-hash-table).118 

trehash-function 

(formake-cqual-hash-tablc).118 

trehash-siz.e 

(for make-equal-hash-table).118 

trehash-threshold 

(for make-equal-hash-table). .118 
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relalivc-namcs 

(fordefpackagc) . ..653 

relalive-namcs-for-me 

(for dcfpackagc) ................ 653 

: reload 

(for makc-syslcm).667 

:reprcscmaiion 

(formakc-arca). . .. .298 

aequircd-flavors 

(fordcfflavor). 426 

irequircd-inil-kcywords 

(fordcfflavor). 425 

: roqii ired-instance-variablc.s 

(fordcfflavor) . .. 425 

: required-methods 

(for defflavor).425 

;restart-after-boot 

(for process- ru n- function).691 

:rcstart-aAer-rescl 

(for process-run-function). ..691 

:rctry 

(forsys:packagc-not-found).651 

chaos:rfc-rcccivcd-state 

(for connection state).. 614 

chaos:rfc-sent-slale 

(for connection state). .614 

:roman 

(for timc:month-string) . ..783 

:room 

(for make-area).298 

:run-reasons 

(for make-process).. 690 

:run-time-altematives 

(for dcfllavor). ..429 

:safe 

(for make-stack-group).260 

:selcctive 

(for make-system). 667 

(for load-patches).. . 676 

;settable-instance-variables 

(for defflavor) . ..424 

:sg-area 

(for make-stack-group).259 

(for make-process). 690 

shadow 

(for defpackage) ..653 

shadowing-import 

(for defpackage).. . 653 

:short 

(for tirac:month-string). 783 

(for timc:day-of-the-weck-string).783 


:short-name 

(fordefsystem). .661 

:silcnt 

(for makc-syslcm). 667 

(for load-patches).676 

:simple-p 

(for make-process).690 

rsinglc 

(for sctsynlax). 539 

:sile 

(for load-patches). .675 

:sizc 

(for makc-cciual-hash-tablc).117 

(formakc-arca). 297 

size 

(for defpackage).652 

:size-macro 

(for dcfstrucl). 382 

;size-symbol 

(for dcfstruct). 382 

:sort-function 

(for meter:analyze). .789 

rsorted 

(for fs:directory-list).599 

:spccial-instance-variables 

(fordcfflavor).424 

'.special-pdWarea 

(for make-stack-group).259 

(for make-process).690 

:special-pdl-size 

(for makc-siack-group).259 

(for make-process).690 

:spell-server-hosts 

(for defsite). .. .813 

:splicing 

(for setsyntax). .539 

:spool 

(for hardcopy- file).786 

:stack-group 

(for meterranalyze).789 

(for make-process). .690 

rstandalone 

(for defsite). 812 

:step 

(for trace).. . .738 

:stepcond 

(for trace)..738 

:stream 

(for fquery)..769 

rstring 

(for prompt-and-rcad)..454 

:string-Iist 

(for prompt-and-read). ..454 

:slring-or-nil 

(for prompt-and-read).• -454 
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istibmii 

(for open).... 585 

:summari/.c 

(for mctcrranaly/c) .78‘> 


super 

(rordcfpackagc).(>55 

:super-inwgc 

(for open).58h 

rsuperior 

(fors.vs:wilh-hclp-slream).47.) 

:swap-sv-of-sg-lhal-c.ills-mc 

(for make-prrx'c.ss).(iW 

(forniako-slark-group). ..259 

:swap-sv-on-c;ill-oiH 

(for luake-slaek-group).2.59 

(for makc-process).890 

:sys-host 

(fordefsitc).811 

:sys-hosi-translaiion-alist 

(fordefsitc).8I1 

:sys-login-ii!unc 

(fordefsitc).812. 

:sys-login-ptissword 

(fordefsitc).812 

tsystems 

(for lo!id-patchc.s).675 

temporary 

(for open).585 

supdup;tcrminal-bcll 

(for beep). 458 

Most 

(for niakc-cqual-hash-tablc).1.17 

itimcs 

(for defstrua).382 

;tirnc/one 

(fordefsitc) ..813 

:trap-cnable 

(for makc-stack-group).259 
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(for inake-piwe.ss).(iW 

;ti'a' 

(fordefslnict). 377 

:iypc 

(forsi:printing-random-objcct). ..513 

(lot niakc-ai'ray).168 

(forfquery).769 

(fordcfsiruci) ..376 

(for defstnict slot option)..375 

:typcd-ariay 

(fordefstruet).. . ,376 

:unrcleascd 

(f»>r load-patches).675 


use 

(fordefpackage).652 


: usual - Im - name- prefix 

(fordefsitc). .812 

rvalue 

(for trace).739 

.vector 

(fordefstruet).376 

: verbose 

(for load-patches).676 

:verify-lni-dumps 

(fordefsitc).814 

rvsp 

(for hardcopy-file).785 

rwarm-htxit-action 

(for procras-run-function).691 

(formake-pKxcss).690 

rwaruings-pathnamc-dcfaull 

(for defsystem).6(>2 

rwhcrcin 

(for trace).739 

rwidth 

(forsysrwith-hclp-strcam). 472 

rwritc 

(firrfsrcomplctc-pathiiamc).602 

rxgp 

(for printer-type).785 
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:propcriy-list {forsi:propcrty-list-mixin).446 
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sys:%aging-dcpth .. 295 

sys:%count-agc-nushcd-pagcs.. .295 

sys;%c()unt-agcd-pagcs. 295 

sys:%count-cha()s-transniil-aborts ..293 

sys:%counl-cons-work.293 

sys:%count-disk -ccc-correctcd-errors.294 

sys:%c()unl-disk-crrors.294 

sys:%c(Hiiil-di.sk-pagc-rcad-opcrations.. . 294 

sys:%coiint-disk-pagc-rcads. 293 

sys:%c{)unt-disk-pagc-wrilc-busys.. , 294 

sy.s:%coiiiit-disk-p.igc-writc-opcrations . . . . . . . 294 

sys:%couiit-disk-pagc-writc-wails . . . . . . . . .294 

sys:%count-disk-pagc-wrilcs.293 

sys:%counl-disk-prcpagcs-nol-used.. 294 

sys:%counl-di.sk-prepagcs-uscd . . ...294 

sys:%count-disk-rcad-coinparc-difrcrcnccs . . . . .294 


Kys:%count -disk - read -compare- rereads.294 

sys:%coimt-disk-read-comparc-rcwrilcs.295 

sys:%c«iiiit-disk-rccalibralcs.294 

sys:%counl-findcorc-cmcrgcncics ..295 

sys:%counl-rindcorc-stcps. 295 

sys:%coiint^firsl-lcvcl-map-rcloads.293 

sys:%count-fresh-pagC!S. 293 

s.Vs:%coimt-mcta-bits-map-rcloads.,293 

sys:%coiint-pdl-bii(Ter-mcniory-faults.. . 293 

sys:%coiml-pdl-biilTcr-read-faults. ..293 

sys:%coui)l-pdl-bulTcr-wri(c-faults ..293 

sys:%couiU-.scavcnger-work. 293 

sys:%rouiil-sccond-level-map-rcloads.293 

sys:%disk-error-log-pointcr.295 

sys:%disk-wait-lime..294 

sys:%iv-clock-rate.. . ; . 293 
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%%arg-de.sc-nm-arg.s. ..244 

%%arg-dcsc-min-args.243 

%%ch-char ..206 

' %%ch-ront .. .207 

%%kbd-Ghar. 206 

%%kbd-control. .. 207 

%%kbd-comrol-incla . .. 207 

%%kbd-hypcr ..207 

%^!!ikbd-nicta. ..207 

%%kbd-nu(usc-bulton.207 

%%kbd-mousc-n-clicks. 207 

%%kbd-supcr . ..207 

%% 11 -all-bul-cdr-code ..279 

%%tl-all-bu(-poinlcr ..279 

%%q-all-but-typcd-pointer ..27R 

%%q-cdr-codc. .278 

%%q-data-lypc. 278 

%%q-high-half. ..279 

%%q-low-half.279 

%%q-pointer. 278 

%%q-poinler-within-page. 278 

%%q-typcd-pointer.278 

%arg-dcsc-evaled-rcst. 244 

%arg-dcsc-fcf-bind-hair. ..244 

%arg-dcsc-fcf-quole-hair.244 

%arg-dcsc-interprcted... ^ ... 244 

%arg-desc-quoted-rest.. . 244 

sys:%chao.s-csr-address.. . 290 

sys:%currcnt-stack-group-calling-args-number ... 289 

sys:%currcnt-stack-group-cailing-args-pointcr. . . . 289 

sys:%curreht-stack-group-state.. . 289 

sys:%disk-blocks-per-cylinder.291 

sys:%di.sk-blocks-per-track.291 

sys:%disk-iun-]ight.291 

sys:%disk-switdjes. 284 

sys:%crror-handler-stack-group.290 

sys:%gc-flip-ready. 291 

sys:%gc-generation-number.291 

sys:%inhibit-read-only. 290 

sys:%initial-ref..289 

sys:%initial-stack-group ..290 

sys;%loaded-band.291 

%mar-high.290 

%mar-low. . ..290 

sys;%mc-code-exit-vector.291 

sys;%metcr-buffcr-pojnter. 292 

sys:%meter-disk-address.292 

.sys:%meter-disk-count.292 

sys:%mcter-global-enable ..292 

sys:%metcr-microcode-enables.788 

%microcodc-vcrsion-number. 289 

sys:%number-of-micro-cntries. 289 

sys:%page-cons-alann.290 

sys:%qlaryh . ..291 


sys:%qlaryl. 291 

sys:%rcgion-cons-alarm.290 

sys:%schediilcr-slack-group . . ..290 

sys:%trap-micro-pG.. 289 

* . . .. .7% 

•*. . ..7% 

. .797 

‘all-davor-names*.415 

‘all-packages*. 656 

fs;*always-mcrge-lypc-and-version*.555 

*applyhook*. .748 

si:*batch-mode-p*.. . .668 

sys:*break-bindings*.797 

*dcbug-io* ..460 

eh:*debug-io-ovcrride*. .727 

si:*defaull-bit-array-printer* ..786 

limc:*dcfaull-datc-prinl-mode*.. . .779 

cli:*dcfault-pathnanic-dcraults*.556 

*dcfault-pathname-defaults*.• • • -556 

si:*dcfault-printer*.786 

fs:*defaults-arc-per-host*.555 

si:*dont-recompile-navors*.421 

‘error-output*.. . .460 

‘evalhook*.748 

•features*.803 

si:*file-transformation-function* ..668 

si:*flavoT-compilations*..423 

fs;*gcncric-basc-type-alist*.561 

eh:*inhibit-debuggcr-procecd-prompt* ...... .727 

fs:*ils-uninteresling-types* ..568 

•load-verbose*. 592 

*macroexpand-hook*.344 

Si:*make-system-fonns-to-be-evaled-after*.668 

si:*raake-system-fomis-to-be-evaled-before* . . . .668 

si:*make-system-forms-to-be-evalcd-finally* . . . .668 

‘modules*.672 

fs:*name-speciried-default-type*.555 

‘nopoint..514 

‘package* ..637 

fs:*paihname-hash-table*.560 

fs:*pathname-host-list*.577 

‘print-array*.515 

‘print-base*. .514 

*print-case*. . ..515 

*print-circle*.514 

‘print-escape*.514 

*print-gensym* ..515 

*print-lenglh*.515 

‘print-level*.515 

*print-pretty*.514 

*print-radix*.514 

*query-io*..460 

si:*qucry-type*.668 
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*random-.slatc* . . . . . . . ... ... . . . .157 

*rcad-basc* .. 517 

*rcad-dcfauU-noal-fomiat*. . ... . , 518 

*rcad-suppress*. ..542 

*rcadtable*. . .. 536 

Ki:*rcdo-all* ..668 

si:*silcnl-p*... 668 

*siandard-input* . .. 459 

*siandard-outpul*. . .. 460 

si:*.syslcm-bcing-dcfincd*.669 

si:*sysicm-bcing-iradc*. 668 

*tcrniinal-io*. ................. 460 

timc:*tinic/one*. ... . . . 782 

si:*top-lcvcl-transfornialions* ..668 

*lracc-output*. 460 

•values*.• • ... 797 

+ . ........ 796 

+ + .. 796 

+ + +. 796 

-. 796 

// .. 796 

Un .. 796 

//////.. . -797 

sys:a-memory-countcr-block-names . ..295 

sys:a-mcmory-localion-names. . ..292 

sys:aclivc-processes.686 

sys:all-proce.sses. . ..686 

allow-variablcs-in-funcUon-position-switch.315 

alphabctic-casc-affccts-string-comparison ..218 

sys:amem-cvcp-vector. 292 

chaos:ans-op.621 

applyhook. 748 

area-list.298 

arglisl.740 

airay-bits-per-element, . ..165 

array-dimcnsion-limil.162 

array-clcmcnls-per-q.165 

sys:array-index-order.183 

array-rank-limit..162 

array-total-size-limit.162 

array-types.165 

art-16b.163 

art-lb. 163 

art-2b. .. . 163 

art-32b. 164 

art-4b. . ..163 

art-8b. 163 

art-complex.164 

art-complex-float. 164 

art-complcx-fps-float.165 

art-fat-string. 163 

art-float. 164 

art-fps-float. 164 


arl-half-fix . .. 164 

art-q. 163 

art-q-list .. 163 

arl-reg-pdl. 165 

ari-spccial-pdl. . ^ i.. 165 

art-stack-group-head .............. 165 

art-string ................... 163 

siiasstKiatcd-machine .............. 815 

background-cons-area. .. . 297 

base. 514 

boolc-1..153 

boolc-2. .. 153 

boole-and. 153 

boole-andcl. 153 

boole-andc2.. ... 153 

boole-clr ..153 

boole-eqv..153 

boole-ior ..153 

boole-nand .. 153 

boole-nor..153 

boole-orcl. 153 

boole-orc2. 153 

boole-sct. 153 

boolc-xor. 153 

call-argumcnts-limit. .47 

edr-error.279 

edr-next ..... . 279 

cdr-nil .. .279 

cdr-normal.279 

chaos;ans-op. 621 

chaos:cls-<v.621 

chaos:dat-op.621 

chaos;eof-cqj. . 621 

chaos;first-data-word-in-pkt.619 

chaos:los-op.621 

chaos:lsn-op. 621 

chaos:max-data-words-per-pkt.619 

chaos:opn-op.621 

chaos:rfc-op. . 621 

chaos:server-alist..616 

char-bits-limit. 206 

ehar-code-limit ..206 

char-control-bit . .. 206 

char-font-limit. 206 

char-hyper-bit. 206 

char-meta-bit.206 

char-super-bit. 206 

cli:*default-pathname-defaults*. 556 

sys:clock-function-list.. . 686 

diaos:cls-op. 621 

si:coId-!oad-stream. . 470 

sixommon-lisp-rcadtable. 536 

compile-encapsulations-flag.302 

compilerxompiler-verbose .. 303 

compiler:peep-enable ..303 


8-JUN-84 















































































































I isp Miichinc Manual 


837 


Variable Index 


compilcr:qc-rilc-clicck-indeiilation ..304 

compiIcr:warn-on-errors.. . 309 

cli:condition-dcfaull-handlers. . ... . 705 

chxondilion-handlers.705 

ch;condilion-rcsumc-handlcrs.726 

ciirrcnl-proccss. 684 

ciirrcnt-stack-group.258 

ciirrcni-siack-group-rcsumcr ..258 

sys:currcntly-prcparcd-shcel ..291 

cliaos:dai-op. 621 

debug-io.460 

dcfaull-cons-arca.297 

doublc-float-cpsilon.159 

double-floal-ncgaiivc-cpsilon. . .. 160 

dtp-array-hcader.271 

dlp-array-poinlcr. 271 

dip-body-forward .. 272 

dip-character.• ■ ..271 

dip-clo.sure.'. . . 271 

dlp-cntily.271 

dip-cxlcndcd-number.271 

dlp-cxlernal-valuc-ccll-poinler.272 

dlp-fcf-pointer. 271 

dip-fix.271 

dip-free. 272 

dip-gc-forward... 272 

dip-header . .. .271 

dip-hcader-forward.. . 272 

dip-insiance. 271 

dip-insiance-header. 271 

dip-list.271 

dip-locative. 271 

dtp-null.271 

dtp-one-q-forward. .............. 272 

dip-sclcct-mcthod .. 271 

dtp-sclf-ref-pointer.. 272 

dtp-small-flonum.271 

dtp-stack-closure. . .. 271 

dtp-stack-group.271 

dtp-symbol ..271 

dtp-symbol-header. 271 

dtp-uap. 272 

dtp-u-entiy. 271 

eh:*debug-io-ovcrride*.727 

eh:*inhibit-dcbugger-proceed-prompt*.727 

ehxondilion-dcfaull-handlers. 705 

ehxondition-handlers.705 

ehxondition-resumc-handlers.726 

eh;pdl-grow-ratio.260 

characc-conditions .. 717 

sixncapsulation-standard-order. 241 

chaos:eof-op.621 

error-output. ..460 

errset. 712 

evalhook.748 


sy.sxxlra-pdl-area . ..299 

sys:fdcfinc-filc-palhname . . . ...239 

sys:filc-local-dcclaralions . . ..304 

chao.s:firsi-daia-word-in-pkl. .619 

fonnai:y-or-n-p-choice.s. 771 

fonnai:y-or-n-p-options ..771 

formai:ycs-or-no-p-options. ...771 

fs:*always-mcrgc-lypc-and-vcrsion*..555 

rs:*dcfaulls-arc-per-hosl*.555 

rs:*gcncric-basc-lypc-alist*..561 

fs:*its-uninlcrcsting-lypcs* . ..568 

fs:*nanic-spccificd-dcraiili-lypc*.555 

fs:*pathnamc-ha.sh-tablc*. .560 

fs:*pathiiamc-host-li,sl*.577 

fs:host-unil-lifctime.608 

fsilast-filc-opcned. .556 

fs:rccord-passwords-flag. .608 

fs:uscr-host-password-alisi. .608 

fsiuscr-uhamcs ..608 

si:gc-flip-minimum-ratio.. . .798 

si:gc-flip-ratio.798 

gc-on.797 

si:gc-reclaim-immediately. .798 

si:gc-rcclaim-immcdiatcly-if-neccssary.798 

si:host-alist.577 

fs:host-unit-lifetime.608 

ibase.517 

ignore. 309 

inhibit-fdcfinc-warnings.240 

.si:inhibil-idic-scavenging-flag ..798 

inhibit-scavenging-flag.290 

inhibit-scheduiing-flag.685 

inhibit-slylc-warnings-switch.316 

si:inilial-common-lisp-readtable . . . . ..536 

siiinitial-process.686 

siiinitial-rcadtable..536 

si; initialization-keywords.775 

internal-time-units-per-second.777 

lambda-list-keywords.44 

lambda-paramelers-Kmit.43 

fs:lasi-filc-opened.556 

leasl-negativc-double-float.159 

least-ncgative-long-float. 159 

leasi-ncgative-short-float.159 

least-negative-angle-float.159 

Icasl-positive-double-float.159 

Icast-positive-long-float. 159 

Icast-positivc-short-fioat . ..159 

least-positive-single-float.159 

sysilexieal-environment ..292 

lisp-crash-list.797 

siilogin-history.808 
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logout-list. 800 

long-lloat-epsilon ..159 

long-noat-ncgativc-cpsilon.160 

chaos:los-op. 62J 

chaos:lsn-op. 621 

macro-compiled-program. ...100 

chaos:max-data-words-per-pkt.'. . . . 619 

metertmelered-objecLs. 788 

most-neg.itive-doublc-floal. . ..159 

most-negative-fixnum. 158 

most-ncgativc-long-flaH. .. 159 

niost-negative-short-floal. 159 

niosl-negalive-single-float . . . . ...159 

most-positive-doublc-float .. 159 

most-positive-fixnum.159 

most-posilivc-long-float. 159 

most-posilivc-shoil-float.159 

mosi-posilivc-single-float.159 

mulliple-values-limit.59 

s>s:nr-sym.300 

sys:number-cons-area ..289 

obsolete-function-warning-switch..315 

open-code-map-switch.316 

chaos;opn-op. .621 

sys:p-n-string.300 

package ..... . 637 

ch:pdl-grow-ratio. .. 260 

compilcrtpccp-enable. 303 

permanent-storage-area.299 

pi.147 

sys:pkg-area .. 300 

pkg-global-package ..657 

pkg-keyword-package .. 657 

pkg-systcm-package.657 

prinl. 7% 

prinlength.515 

prinlevel.515 

sitprint-readably.513 

sys:piocc.s.sor-type-code.288 

sys:property-lisl-area.300 

q-data-types.272 

compilcr:qc-file-check-indenlation.304 

query-io.460 

read-check-indentation.533 

rcad-prcscrve-delimiters. 531 

readtable.536 

fs: record-passwords-flag ..608 

sys:rcsidcnt-symbol-area.300 

chaos;rfc-op.621 

room.793 

rubout-handler.502 


nin-in-m,aclisp-switch. 315 

sys:scavengcr-ws-cnablc............. 290 

.sys:schcdulcr-stack-group. 686 

self.. 420 

sys:self-mapping-tablc. 442 

chaostserver-alist.. 616 

short-no.it-epsilon . .. 159 

short-float-negative-epsilon . ..159 

si:*b.atch-niodc-p*. 668 

si:*dcfaull-bil-array-printcr*. 786 

si;*dcfault-printer* ... . . . ... • 786 

si :*dont-recompile-flavors*. 421 

si;*rilc-iransfomialion-runction* ..668 

si:*navor-compilations*.423 

si:*makc-systeni-forms-to-bc-cvalcd-artcr* .... 668 

si:*makc-systcm-fomis-to-bc-cvalcd-bcfore*. . . . 668 

si;*makc-.syslem-fomis-to-be-cvalcd-finally*. . . . 668 

si:*qucry-type*. .668 

si:*rcdo-all*. 668 

si:*silent-p*.668 

si:*system-bcing-dermcd*. 669 

si:*system-bcing-made*. .668 

si:*top-level-transformalions*. 668 

sitassociated-raachinc .. .815 

si:cold-load-strcam..470 

si:common-lisp-rcadtable. 536 

sitcncapsulation-standard-ordcr..247 

si:gc-flip-minimum-ralio . ..798 

sitge-flip-ratio.798 

si:gc-rcclaim-immediatcly ..798 

si:gc-reclaim-immediately-if-necessary.798 

si:hosi-alist. 577 

si:inhibit-idle-scavenging-flag ..798 

sitinilial-common-lisp-readtable.536 

sitinitial-process.686 

si:inilial-readtable. . 536 

sitinitialization-keywords.775 

sitlogin-histoiy.808 

si.print-readably. 513 

si:.standard-readtable . .. .536 

si:user-init-oplions.801 

single-float-epsilon.159 

singlc-float-negative-epsilon.160 

site-name. 814 

standard-input.459 

standard-output ..460 

sitstandard-rcadtable. 536 

sys:%chaos-csr-address.290 

sys:%currcnt-stack-group-calling-args-number ... 289 
sys:%current-stack-group-calling-args-pointer. ... 289 

sys:%current-stack-group-state.289 

sys:%disk-blocks-pcr-cylinder. 291 

.sys:%disk-blocks-per-track. ........... 291 

sys:%disk-run-light.291 

sys:%disk-switches.284 

sys:%crror-handler-stack-group.290 


8-JUN-84 





































































































I isp Miichinc Miimial 


839 


Variable Index 


sys:%gc-flip-rcady.. 291 

sys:%i!C-gcncration-numbcr ... . 291 

sys:%inhibit-rcad-only..290 

sys:%inilial*fcr. 289 

sys:%iiuiial-siack-group.290 

s.\s;%loadcd-band. . ..291 

svs:%inc-codc-cxit-vector.291 

sys:%nictcr-buffcr-pointer. 292 

s\s:%mctcr-di.sk-addrcss.292 

sys:%mctcr-disk-count.292 

s.\s:%mctcr-global-enable ..292 

sys:%mctcr-microcodc-enable.s.788 

sys:%min)ber-of-micro-cntries.289 

s.\s;%p.agc-cons-alarm. 290 

sys:%qlaryh.291 

sys:%qlaryl.291 

sy.s:%rcgioii-cons-alarm.290 

sys:%schedulcr-stack-group. 290 

sys:%trap-micro-pc.289 

sys:*bieak-bindings* ..797 

sys:a-mcmory-countcr-block-names.295 

sys:a-nicmor>-location-names.292 

sys:aclivc-processcs.686 

sys:all-processcs.686 

sys;amem-cvcp-vector.292 

sys;array-index-order .. .183 

sys;clock-function-list.686 

sys:curicntly-prepared-shcct.291 

sys:extra- pdl-area.299 

sy.s:fdefinc-file-pathnainc.239 

sys:file-local-declarations.304 

sysdcxical-environment.292 

sys:nr-sym.300 


sysauimbcr-cons-area. . .289 

sys:p-n-string. ..300 

sys:pkg-arca.300 

sys:proccssor-typc-code. . .288 

sys;propcrty-list-area ..300 

sys;residcnt-symbol-arca ..300 

sys:scaveiigcr-ws-enable. 290 

sys:schcdulcr-stack-group.686 

sy's:sclf-niapping-table.442 

tail-recursion-flag . . ..55 

tcniiinal-io.460 

limc;*defaiill-date-print-niodc*. 779 

timc;*timexone* ..782 

trace-coniiiilc-flag ..741 

characc-conditions.717 

trace-output.460 

fs:uscr-host-password-alist. . .608 • 

user-id. 800 

si:uscr-init-options.801 

fs:uscr-unamcs. 608 

values.740 

compilcr:warn-on-errors.309 

working-storage-area.299 

fonnai:y-or-n-p-choices.771 

formatiy-or-n-p-options..771 

fomiat:ycs-or-no-p-options.771 

zunderflow.137 
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... . 140 

S. 140 

2:. . . . .. 139 

%24-bit -diflcrence . .. .160 

%24-bit-plus.. 160 

%24-bit-tinics... . , . .160 

%aciivate-opcn-call-block.284 

%al!ocalc-aiid-inilializc.. . .280 

%allocatc-and-initializc-array . , ... . . . . . .280 

%arca-numbcr .. 299 

%args-info. 244 

%assurc-pdl-room. . ... . 284 

%bind. 284 

sys:%binding-inslances. 287 

%bli ........ ..280 

%blt-typed. 280 

.sys:%change-page-sta(us..286 

sys;%compiiic-page-hash.286 

.sys:%crcatc-phy.sical-page. 286 

%data-type.274 

sy.'!:%dclete-physical-page.287 

sys:%disk-rcstore.287 

sys:%disk-save ..287 

%div. 146 

%divide-double.161 

%find-structurc-hcader.279 

%find-slructure-lcader.279 

%noat^double. 161 

sys:%halt.295 

sys:%intcrnal-value-oell. . 288 

%logdpb.157 

%logldb ..157 

%make-pointer. 274 

%make-pointcr-offset.274 

%multiply-fractions. 161 

sys;%nubus-physical-address.283 

sys:%nubus-read. . 283 

sys;%nubus-write ..283 

%opcn-call-block.283 

%p-cdr-code.277 

%p-contcnt.s-as-locative.275 

%p-contcnLs-a.s-locative-offset.275 

%p-contenls-offset.275 

%p-conlcnts-safe-p.275 

%p-conlems-safe-p-offset .. . 275 

%p-data-type.'.277 

%p-dcposit-ficld.277 

%p-dcposit-ficld-offset.277 

%p-dpb.277 

%p-dpb-offsct.277 

%p-ldb.276 

%p-ldb-offset. 276 

%p-mask-field. 277 


%p-mask-ficld-olTsct .. 277 

%p-pointcr. 277 

%p-pointcrp. .. 275 

%p-poinlcrp-ofTscl .. 275 

%p-safc-conlcnts-offsct.276 

%p-slorc-cdr-codc . .. 278 

%p-slorc-conlcnts. 276 

%p-slorc-contcnt.s-offsct. .. 276 

%p-siorc-dala-typc. . ..278 

%p-storc-pointcr.. .278 

%p-storc-lag-and-pointcr. 276 

sys:%pagc-slalus. 286 

sys;%phy.sical-addrcss ..286 

%pointcr. 274 

%poinlcr-dilTerence.. 160.274 

%poinlcr-plus.160 

%pointer''limes .. . 160 

%pointer-type-p.275 

%pointerp. 274 

%pop.284 

%push. 284 

%region-number ..299 

%rcmaindcr-double. 161 

. %stack-framc*pointer.278 

%slore-conditional.282 

%string-equal ..217 

%string-search-char. . ..218 

%siructure-boxcd-size.279 

%structurc-total-size.280 

%unibus*read.282 

%unibus-write .. 282 

sys:%using-binding-inslances.287 

%xbus-read. 282 

%xbus-write.282 

sys:%xbus-write-sync.282 

•.142 

*$.142 

•array. 187 

•break-on-warnings*.709 

•catch.81 

•dif. 146 

•expr.. 316 

•fexpr.316 

•lexpr.316 

•plus.146 

•quo.146 

•throw. 81 

•times.146 

•unwind-stack.82 

+.141 

+ $ ..141 
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cli:// 
// . 
//$. 
n- 

u. 

i+$ 
i-. 
i-$ 

<■ . 
<=. 


>....... • 

>= . . • • 

^define. 

abs. 

chaos;accept. 

aeons.. 

acos. 

acosh.. 

add-initialization. 

fs;add-logical-pathname-host 
compilcr:add-optiniizer . . 

addl.. 

adjoin. 

adjust-array. 

adjust-array-size. 

adjustable-array-p .... 

advise. 

si:advise-l. 

advise-within.. 

allocate-resource. 

aloe. 

alpha-char-p. 

alphalcssp. 

alphanumericp. 

metcr:analyze .. 

and. 

chaos:answer. 

chaos:answcr-string .... 

ap-1.. 

ap-l-force ....... 

ap-2.. 

ap-3. 

ap-leader .. 

append . 

apply. . .. 

applyhook. ....... 

apropos. 


, 141 
, 141 

, 142 
. 142 
. 142 
. 140 

. 145 
. 145 
. 145 
. 145 

. 140 
. 140 

. 139 

. 139 
. 139 

. 236 

. 141 
. 616 
. 109 
. 148 
. 148 
. 774 
. 574 
. 313 
. 145 
. 107 
. 176 
. 176 
. 175 
. 742 
. 744 
. 745 
. 126 
. 171 
. 210 
. 221 
. 210 
. 788 
. .64 
. 617 
, . 617 
. . 172 
, . 171 
. . 172 
. . 172 
. . 172 
. . .94 
. . .47 
. . 749 
. . 791 


ar-1 . . . • • • • • • 
ar-l-Torcc ...... 

ar-2. 

ar-2-revcrse . . . . . 

ar-3.. • • • 

area-name. 

cli’.aref. 

aref 

eh;arg. 

arg. 

oh;arg-iiame. 

arglist. 

args-info. 

array. 

array-active-lenglh. . . 
array-bits-per-element . 
array-dimension . . . . 
array-dimension-n . . . 
array-dimensions. . . . 
array-displaced-p . . . 
array-element-si/.e . . . 
array-clement-type. . . 
array-clcments-per-q. . 
array-grow ...... 

array -has- fill - pointer-p 
array-has-lcadcr-p. . 
array-in-bounds-p. . 
array-index-offset . . 
array-indexed-p. • • 
array-indirect-p . . . 
array^initialize. . . . 
array-leader. . . . . 
array-leader-length. . 

array-length. 

array-pop. 

array-push. 

array-push-extend . . 

array-rank. 

array-row-major-index 
array-total-size . . . 

array-type. 

array-types. 

arraycall. 

arraydims. 

arrayp. 

as-1. 

as-l-force ..... 

as-2. 

as-2*reverse .... 

as-3. 

ascii. 

aset. 

ash. 

asin. 

asinh. .. 

ass. 

assert . 
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172 
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,170 
,170 
.734 
.238 
.243 
.242 
.243 
.187 
.174 
.165 
.174 
.174 
.174 
.175 
.165 
.173 
.165 
.177 
.175 
.175 
.175 
.175 
.175 
.175 
.179 
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.175 
.174 
.178 
.178 
.178 
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.171 
.174 
.173 
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.187 
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cli:assoc . . 110 

assoc ...... . ... . 110 

assoc-if . . . . . . . . .... . . . . . . . .Ill 

assoc-if-not.Ill 

.issq. 110 

chaos:assurc-cnabled. ... . 625 

cliiaian. 148 

alan. 148 

alan2. .148 

atanh. 148 

aloin.M 


fsibalancc-dircctorics. 603 

beep .. 457 

bigp. 12 

bind. 284 

bit ... .. 172 

bil-and. 180 

bit-andcl. 180 

bil-andc2 .. 180 

bit-eqv. 180 

bit-ior. 180 

bil-nand. 180 

bil-nor. 180 

bit-not..181 

bit-orcl.180 

bit-orc2.180 

bit-test.153 

bit-vcctor-p.12 

bit-xor. 180 

bitbIt ..181 

block .. 77 

boole ..152 

bolh-case-p... . 212 

boundp. 129 

boundp-globally.35 

boundp-in-closure.254 

break.795 

format:breakline.499 

breakon .. 741 

bug.794 

buUast. 96 

byte..155 

byte-position. 155 

byte-size.155 


c...r. . 

caaaar. 

caaadr. 

caaar . 

caadar. 

caaddr. 

caadr . 

caar. . 

caar-safe 

cadaar. 

cadadr. 


87 

87 

87 

87 

87 

87 

87 

87 

97 

87 

87 


cadar. 87 

caddar . . . . . . ... ... . . .87 

cadddr .. 87 

cadddr-safe .. .97 

caddr. ....... . 87 

caddr-safe. .. 97 

cadr .. .87 

cadr-safe . .. 97 

call. ..................... .48 

car. . . . . . . . .. 87 

car-location ..89 

ear-safe. .. 97 

ease ..65 

caseq..65 

catch . ...80 

catch-all ..83 

catch-continuation ... . . 80 

catch-conlinuation-if. 80 

catch-error. 712 

catch-error-restart. 724 

catch-crror-restart-cxplicit-if.724 

catch-crror-rcstart-if ..724 

cease . .. 66 

cdaaar .. 87 

edaadr.87 

edaar. 87 

edadar . 87 

edaddr . 87 

edadr. 87 

edar. 87 

edar-safe.97 

eddaar. 87 

eddadr. 87 

eddar.87 

edddar .. 87 

eddddr. 87 

eddddr-safe.97 

edddr.87 

edddr-safe.97 

eddr.87 

eddr-safe. 97 

edr.87 

edr-safe. ..97 

ceiling.143 

cerror. .. 709 

fs:changc-filc-propcrties. .602 

si:changc-indirect-array.177 

chaostaccept..616 

chaosranswer.617 

chaos:answcr-string. ..617 

chaos:as.sure-enabled. 625 

chaosxlose-conn. 616 

chaos:conn-finished-p. ... . 620 

chaosxonn-forcign-address.615 

chaos:conn-plist. 615 

chaos:conn-rcad-pkts. 615 

chaostconn-state.615 
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chaosxonn-window-availablc.615 

('haosxonncct. . 615 

chaos:coniaci-name. 615 

chaos:dala-availablc. .. 620 

cha<)s:disablc. ..625 

chaos:enablc. 625 

chaos:cval-scrvcr-on.. . 633 

chaos:fesl-answcr-string ............. 617 

cha()s:find-hi>sts-or-lispms-loggcd-in-a.s-u.ser. . . . 634 

chao.s:riiigcr-all-lms.634 

chaos: finish-conn.620 

chaos: forward-all. 617 

chaf)s:get-ncxl-pltt.620 

chaos:gci-pkl. 619 

chaos:host-daia. 625 

chaos:host-up-p. 624 

chaos:inicrrupl-function. .622 

chaos:listcn.616 

chao.s:make-stream ..618 

chaos:may-lransfnit. 620 

chaos:opcn-fprcign-conncction.616 

chaos:apcn-stream.617 

chaos:pkt-link. 622 

chaos:pkl-nbytes. 619 

chaos:pkt-opcode.619 

chaos:pkt-slring.619 

chaos:print-all-pkts.' . . 625 

chaos:prinl-conn .. 625 

chaos:print-pkt. 625 

chaos:read-pkts. 622 

chaos:reject .. 617 

chaos: remove-conn. 616 

chaos'.rcsct.625 

chaos: rctum-pkt.619 

chaos:scnd-pkt. 619 

Ghaos:send-string.620 

chaos:scnd-unc-pkt. 620 

chaos:set-pkt-string.619 

chaos:shout. 633 

chaos:show-routing-path.625 

chaos:show-routing-table .. . 625 

chaos:simple.616 

chaos:sutus. 625 

chaos:up-hosts. 624 

chaos:user-logged-into-hosl-p. .634 

chaos:wait..615 

char.172 

char-bit. 206 

char-bits. 206 

char-code.206 

char-downcase.213 

char-equal.210 

char-font ..206 

char-greaterp .. 211 

char-int. 205 

char-lessp.. . 211 

diar-nanie. 211 


char-not-equal. 210 

char-nol-grciitcrp.211 

char-not-Icssp. .211 

char-upcasc.• • .. 

char//=. 211 

char<. .211 

char< =. .211 

char=. 211 

char>. 211 

char>=.211 

cli:characler.204 

character.^ . .. .204 

characterp..12,204 

chcck-arg. .710 

check-arg-type. .709 

check-type..709 

circular-li.st.93 

cis. .147 

si:cleari-up-static-area.799 

clear-input.451 

clear-mar..750 

clear-output. .. 457 

dear-resource.127 
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cli:aref. 170 

cli:assoc.110 

cli:atan. ..148 

cli:character.204 

cli:close.582 

difdefstruct.393 
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cli:intcrsection . ..108 

cli:listp.11 
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di:rem. .144 

di:rejnove.195 
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cli:some.191 

cli:subst.98 
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di:close.582 

dose.582 
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dosurc-fiinclion. 

closure-variables ........ 

closurep . .. 

clrhash.. 

code-char . . . 

coerce.... 

comment. . .. 

common-li.sp .. 

commonp. 

si:compare-band. 

compiler'compilalioii-define. . . . 

Compile . . . .. 
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compile-file. 
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compile-lambda. 
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compiler-let.. 

compilcr:add-optimi/.cr. 
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compilerrdefoptimizer. 

compiler:fasd-rile-symbols-prcq>erties 

compiler: fasd-font. 

compiler:fasd-symbol-value. . . . 
compiler: function-referenced ... 

compiler:make-obsolcte. 

fs: complete-pathname. 
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complexp. 
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cond.. 

cond-every. .. 

condidon-bind. • • • 

condition-bind-default. 

condition-bind-default-if. .... 

condition-bind-if. 

condition-call. .. 

condition-call-if. 

condition-case. 

condition-case-if. 

condition-resume.. . 

condition-resume-if. 

condition-lypep. 

conjugate.. 

chaos:conn-fmished-p ...... 

chaos:conn-forcign-address.... 

chaos:conn-plist. 

chaos:conn-rcad-pkts ...... 

chaos:conn-state. 

chaos:conn-window-available . . . 

chaos:connect. .. 

cons. 
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consp . 

chaos:contacl-name. 
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254 copy-alist . ..... . . . . 

254 copy-array-contents. . ... . 

1.4 copy-array-contents-and-leader. 

120 copy-array-port ion. 

207 copy-closure. 

21 copy-file . . . . . ... . , 

50 copy-list. 

. 8 fstcopy-pathname-dcraults . . . 

14 copy-rcadtable. 

810 copy-seq.. . . . . 

310 copy-symbol. . .. 

301 copy-tree. 

302 copyalist . .. 

302 copylist. . . 

422 copylist* .. 

302 copysymbol . .. 

13 copytree .. 

316 cos. ... 
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310 cosh.. 

314 count. ... 

314 count-if.. 

318 count-if-not. 

318 fs:crcatc-directory. 

318 fs:creatc-link. 

310 ctypecase. 

310 si:currcnt-band. 
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146 cursorpos. 

12 

189 chaos:data-availabte. 

63 data-type. 

64 time:day-of-the-week-string. . 
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701 time:daylight-savings-time-p. . 

705 deallocate-resource. 

704 deallocate-whole-resource . . . 

703 si:dcbug-warm-bootcd-process. 

704 debugging-info. . . 

702 deef . 

704 declare. 

723 dcclare-llavor-instance-variables 

723 decode-float. 

700 decode-universal-time. . . . . 

147 math: decompose. 

620 def. 

615 fs:dcfault-host. 

615 fs:dcfault-pathname. . . . . . 
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615 dcfconst. 

615 dcfconstant. 

615 defdecl .. 

87 delT .. 
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defsystem.660 

deftype. 39 

defun. ..227 

si;dcfun-compatibilily ..236 

dcfvar.33 

defwrapper . ... . 418 
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eql.69 
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errorp.700 
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eval. 46 
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moor. 145 
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sys:file-operation-with-warnings. .311 

file-position. 587 

fsrfile-propcrties.602 
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fixnump.12 
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float-precision ..l.M 
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float-sign. 151 

floatp. 12 

flonump. . .. .12 

floor .. 143 

rniakiinbound. . 131 
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format. 483 

format:breaklinc ..499 

format :ochar.497 

formattofloat.497 

formatronum. 497 
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formatroutfmt. 496 

format;output. .496 

formatrpad..498 

format rptural.499 
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freturn . .. 82 
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fs:balancc-dircctories.603 
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fs:default-host. 556 
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fset.130 
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fsymeval .. .130 

Uruncate. .145 

si:full-gc ..799 

eh:fun.734 

funcall. 46 

funcall-sclf. 420 

funcall-with-mapping-table.420 

function..48 

function-ccll-location. 131 

function-name.243 

si:function-parent. 241 

compilcr:function-rcfcrenced.310 
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si:function-spcc-lessp.241 

si:function-spcc-putprop. 241 
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fundefine. 241 

g-l-p.177 

gc-off.797 

gc-on. .797 

gc-status ..799 

ged.145 

gensym.133 

gentemp.134 

get.114 
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get-dccoded-time.777 
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get-handler-for.422 
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tinic:gcl-limc. .. 777 

gci-univcrsal-timc. .Ill 

gcichar .. 221 

gctcharn ..•.. 221 

gctdccl. .307 

gcif.... . 115 

gcihash . 119 

getl.• • .. 

globalize. ()44 

go. 79 

graphic-char-p. 210 

greaterp. 139 

grind-top-level. 529 

grinder.528 


intern-local ..645 

inlern-local-soft. 646 

intern-soft. 646 

chaosrintcrrupt-funclion.622 

cli:intcrscction.108 

intersection.. ... 108 

zwci:intcrval-strcam. . .. 472 

niath:invcrt-matrix.183 
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isqrt ..... . 146 

tv:kbd-mouse-p.207 

keywordp ..641 

kill-package.. 654 


haipart . .... . 154 
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hardcopy-file. 785 

hardcopy-status. 786 

hardcopy-stream.786 

hash-table-count ..120 

hash-table-p. 119 
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chaos:host-data.625 
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if.63 
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if-for-maclisp-cise-lispm.315 

if-in-cadr. 288 
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if-in-lambda.288 
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if-in-lispm.315 

if-in-maclisp..315 

ignore.50 

ignore-errors.700 
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import.642 

in-package. 657 
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init-file-pathname.560 

initializations.775 

timetinitialize-timebase. ..782 

input-stream-p.466 

inspect.792 
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int-char.204 
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intern.645 
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Idb. .. 155 
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let... . 31 
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let-if. .. 32 

lexpr-ftmcall. .. . .47 
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lexpr-scnd.. . 407 
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si:lisp-top-level. 795 
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list*. 90 
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list-all-packages. 651 
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list-match-p. .. .92 
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load-patches. 

ch:toc. 

tocal-declare. . ... . 
ch:kKai-name . .. . . ■ 
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location-boundp ... 
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locf. 

log. 
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login. 

login-eval.. 

login-forms. 

login-setq...... 

logior. 

lognand. 

lognor. 

lognol . .. 

logorcl. 

logorc2. 

logout ....... 
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logxor. 
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loop. 
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si:loop-tequal . . . . 
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Ish. 

Isubrcall.. . 
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machine-type . . . . 
machine-version . . . 
macro. ....... 

macro-function. . . . 
maCToexpand. . . . ■ 
macroexpand-1. . . . 
macroexpand-all . . 

macrolet. 
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make-array .... 
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.51 niake-condition.. 

243 makc-dispatch-macro-character 

. 54 makc-ccho-stream .. 

254 makc-cqual-hash-table.... 

423 make-hash-table. 

268 make-instance. 

268 make-list. 

. 14 fs;make-logical-pathname-hosl. 
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147 compilcrtmake-obsolete.... 

801 make-package. 

151 make-pathname .. 
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156 make-plane. 

154 make-process. 
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802 make-sequence. 
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. 152 make-symbol. 

, 152 makc-syn-stream. 

, 152 make-synonym-stream .... 

, 801 make-system. 

. 153 make-two-way-stream . . . . 

. 151 maknam. 

. 804 makunbound. 

. 350 makunbound-globally. . . . . 

. 358 makunbound-in-closure. . . . 

. 369 di’.map. 

. 368 map. 

. 368 map-resource. 

. 368 mapatoms.. 
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. 804 mapeon . 
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. 320 mapl.. 
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. 343 mask-field. 
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mem . . .... . . .104 
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meler:disable.788 

metericnable. 788 

meter:resel. .. 790 

meter:resume-gC‘-process. ..790 
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vcclor. 167 

vcclor-pop.178 

vector-push . 

vcctor-push-cxtcnd. 178 

veclorp .. 12 

liiiic:vcrify-datc. .783 

viewf. 591 

chaos:wait. 615 

warn. 709 

whal-filcs-call.790 

when. 63 

where-is .. 791 

who-calls.790 

whois. 634 

si;wirc-page ..285 

.sys;wiih-help-strcam.472 

with-input-editing. .501 

with-input-from-string.. . 473 

with-lock.688 

wilh-open-file. 580 

with-opcn-file-case. 580 

with-open-file-rctry. 581 

with-open-file-scarch.. 581 

wiih-open-.slream.471 

with-opcn-slrcam-case. .471 

with-outpul-to-string.474 

with-sclf-variables-bound. 421 

with-stack-list .. 112 


with-stack-list*. 112 

with-timeout ..686 

without-inlcrrupt.s . ...684 

write. 528 

wriic-bytc .. .456 

write-char. 456 

write-line.456 

write-meter. .. 292 

write-string. 456 

writc-to-string. 529 

xcons .. .88 

xcons-in-area.88 

si:xr-xrtyi. 541 

si:xr-xruntyi.542 

xstore. 187 

y-or-n-p. .. 768 

yes-or-no-p. 768 

zerop.138 

zwei:inlerval-stream.. . .472 

zwei:save-all-files ..793 
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fqucry. 771 

fs:acccss-crror.. . 606 

fs:circular-link.605 

fsxrcalion-failure.606 

fs:dala-crror.60^ 

rs:dclctc-failurc.(>06 

fs:dcvicc-not-foiind.<>05 

fs:direcl()ry-nol-cniply.606 

fs;dircctoi'\-nol-found . ..605 

fstdom-delctc-Oag-scl.<>0() 

fs;filc-alrcady-cxisLs.(>06 

fs; flic-error.<104 

fs: file-locked.605 

fs:filc-lookup-crror.(>05 

fs; file-not-found.605 

fs:file-opcn-for-oulpul.604 

fsifilc-opcration-failure.<>04 

fs:nic-rcQucsl-railure.<>09 

fs:filcpos-oiit-of-range.605 

fs:hosl-nol-available.609 

fs:incorrccl-acccss-to-directory.606 

fs:incorrccl-acccss-to-file. ..606 

fs:invalid-byic-si7.e. 605 

fs:invalid-rile-attribute.598 

fs:invalid-propcrty-name...607 

fs:invalid-propcny-value.607 

fs;invalid-wildcard.606 

fs:link-targci-nol-found.605 

fsimultiplc-filc-nol-found.605 

fs:nclwork-lossage..609 

fs:no-niore-room.605 

fs:not-available.<>05 

fs:noi-enough-rcsources.609 

fs:pathname-parse-error.558 

fsircnamc-across-direaories. ..607 

fs:rcname-failure .. 606 

fs:rcname-to-exisUng-file..607 

fs:supcrior-not-dircctory.606 

fs:unknown-logical-palhnamc-translation.575 

fs:unknown-opcration.610 

fs;unknown-pathnanie-host.577 

fs:unknown-propcrty.607 

fs;wildcard-not-allowcd.606 

fs:wrong-kind-of-file.606 

math:singular-matrix.. . 184 

sys:abort.726 

sys;arca-overflow.300 

sys:array-has-no-leader.172 

s>s;array-wrong-numbcr-of-dimcnsions.173 

sysibad-array-mixin. 173 

sys:bad-conncction-state ..623 

sys:ccll-conicnts-error.60 

sys:conncction-closcd. 624 

sys:conncction-error.623 


sys:conneclion-lost .. 624 

sys:conncction-no-morc-data. 624 

sys;conncction-rcfuscd.624 

sys:cons-in-fixcd-arca. . ..300 

sys:dividc-by-zcro . . . .. 145 

sysicnd-of-filc.449 

sys.Till-pointcr-nol-fixnum. . ..178 

sysifloaling-cxponcnl-ovcrnow.137 

sysifloaling-cxpoiiciu-undcrnow.137 

sys:host-not-responding.623 

sys:host-nol-rcsponding-diiring-conncction.623 

.sysrhost-stopped-responding ..624 

sys:invalid-function.59 

sys:invalid-function-spcc. 241 

sys:invalid-lambda-list.59 

sys: local-network-error.623 

sysrlock-timcout.688 

sys:mar-brcak.751 

sysimissing-closeparen.535 

sys:nctwork-crror.622 

sysinciwork-rcsources-exhaustcd.623 

sys:no-scrvcr-up.624 

sys:numbcr-array-not-allowcd.173 

.sys:packagc-nol-found.651 

sys:parse-error. 505 

sysipdl-ovcrflow.260 

sys:print-nol-rcadable. 513 

sys:rcad-end“of-file.534 

sysircad-error.534 

sys:rcad-lisl-cnd-of-file. ..534 

sys:rcad-string-cnd-of-file. ..535 

sysircad-symbol-end-of-file.535 

sysrredcfinition.240 

sysrregion-tablc-ovcrflow.300 

sys:rcmote-neiwork-crror.623 

sys:r}ilacd-wrong-rcpresentation-type.113 

sys:subscript-out-of-bounds.173 

sys:throw-tag-not-seen.81 

sys:too-fcw-arguments.59 

sys:ioo-many-arguments.60 

sys:unbound-closurc-variable.61 

sy's:unbound-instance-variable. 61 

sysrunbound-spccial-variable.61 

sys:unbound-variable.61 

sysiunclaimcd-mcssage.423 

sys:undcfined-function.61 

sys:undcfincd-kcyword-argument.60 

sysrunknown-address.623 

sys:unknown-host-name.576 

sys:unknown-locf-rcfcrence . ..37 

sys:unknown-sctf-rcfcrence.37 

.sysivirtual-mcmory-overflow.300 

sys:wrong-stack-group-state.260 

sys;wrong-lype-argument.61 
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sys:/.cro-log 


. . 147 


sys:/ero-lo-ncgaiivc-powcr 


146 




IP 



